Skill · Coding

domain-model-and-adr

Builds a glossary of the domain's terms from code and conversation, picks one canonical name for each concept, stress-tests the model against edge cases, writes architecture decision records (ADRs) for non-obvious choices, and flags code names that disagree. Use when starting a new feature, when terminology is confusing or inconsistent, or when asked for a domain model, glossary, ubiquitous language, ADR or decision record.

The skill itself. Agents read the name and description first and load the rest only when a task matches.

domain-model-and-adr/SKILL.md
---
name: domain-model-and-adr
description: Builds a glossary of the domain's terms from code and conversation, picks one canonical name for each concept, stress-tests the model against edge cases, writes architecture decision records (ADRs) for non-obvious choices, and flags code names that disagree. Use when starting a new feature, when terminology is confusing or inconsistent, or when asked for a domain model, glossary, ubiquitous language, ADR or decision record.
---

# Domain model and ADRs

## Steps

1. Collect terms. Read the relevant code (types, tables, routes, function names) and the conversation. List every noun (Order, Cart, Workspace) and verb (checkout, archive, invite).
2. Write a glossary: one term per line, a one-sentence definition, and where it lives in the code.
3. Find conflicts: synonyms for the same thing (Account vs Workspace vs Team), one word used for two things, terms the user says that the code doesn't. For each, pick a canonical term, give the reason, and list the aliases to retire. If the choice is a judgement call, recommend one and ask the user.
4. Note relationships and rules: cardinality (a Workspace has many Projects), lifecycle states and allowed transitions, invariants (an Order total is never negative).
5. Stress-test the model with edge cases: deletion and archiving, ownership transfer, duplicates, concurrent edits, time zones, money and rounding, a user in two workspaces, partial failure. For each, say what the model says happens. If it can't answer, that's an open question or a decision to make.
6. Write an ADR for each non-obvious choice, using the layout in the example. If the repo already has ADRs (look for docs/adr/ or docs/decisions/), follow their numbering and format; otherwise use `docs/adr/0001-short-title.md`.
7. Save the glossary next to them (an existing glossary file, or `docs/glossary.md`).
8. Flag code that disagrees with the glossary: file, current name, canonical name. Propose renames; don't make them unless asked.

## Rules

- One definition per term. If you need two, it's two terms.
- Definitions use plain words and only glossary terms that are defined too.
- An ADR records a decision that was made. If it's still open, list it as a question, not an ADR.
- Keep each ADR under a page, and record the options you rejected and why.
- Don't change code or schema as part of this skill.

## Example output

```
Glossary
- Workspace: the billing and permission boundary; owns Projects. (src/db/workspace.ts)
- Member: a User's role inside one Workspace. Alias to retire: "Seat".

ADR 0003: Soft-delete Projects
Status: accepted
Context: users restore deleted projects within days; hard delete loses history.
Options: hard delete; soft delete with deleted_at; archive table.
Decision: soft delete with deleted_at, purge after 30 days.
Consequences: every Project query filters on deleted_at; a nightly purge job is needed.
```