Domain Modeling

Actively build and sharpen the project's domain model as you design. This is the active discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallize. (Merely reading CONTEXT.md for vocabulary is a one-line habit any skill does — that is not this skill. This skill is for when you are changing the model.)

Why it matters: at the start of a project the developer and the domain experts speak different languages, and the agent is dropped in to guess the jargon — so it uses 20 words where 1 would do. A shared language fixes that. The same precise term flows into conversation, variable names, file names, and tests; the codebase gets easier to navigate; the agent spends fewer tokens thinking.

Phase 0 — Load profile & locate the model

1. Read .claude/PROJECT.md → Domain (the seed vocabulary and roles) and Architecture (so terms map to real modules). If PROJECT.md is missing or still TEMPLATE, you can still run (lean on the root CLAUDE.md if it carries the facts) — but tell the user /bootstrap will wire the glossary location into the profile.
2. Locate the model files (lazily created — see below):
   • CONTEXT.md — the glossary, at the repo root (or the path named in PROJECT.md → Domain). If a CONTEXT-MAP.md exists at the root, the repo has multiple bounded contexts; the map points to where each CONTEXT.md lives.
   • docs/adr/NNNN-<slug>.md — architectural decision records (or the ADR location named in PROJECT.md).

File structure

Most repos have a single context:

/
├── CONTEXT.md                 ← the ubiquitous-language glossary
├── docs/adr/
│   ├── 0001-event-sourced-orders.md
│   └── 0002-postgres-for-write-model.md
└── src/

Multi-context repos add a root CONTEXT-MAP.md and put a CONTEXT.md (and optional context-specific docs/adr/) inside each context directory. Default to a single CONTEXT.md — introduce the map only when contexts genuinely diverge.

Create files lazily. Don't scaffold empty docs. Create CONTEXT.md when the first term is resolved; create docs/adr/ when the first decision needs recording.

During the session

Run these continuously while designing — this is a background discipline, not a phase you finish.

Challenge against the glossary

When the user uses a term that conflicts with the existing language in CONTEXT.md, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"

Sharpen fuzzy language

When the user uses a vague or overloaded term, propose a precise canonical one. "You're saying 'account' — do you mean the Customer or the User? Those are different things." Pick one term per concept and an _Avoid_ list of the synonyms it replaces. A word that names both a kind and one of its instances (a Product that is also the catalogue entry) is the same error a level up — split the kind from its instances before any hierarchy.

Discuss concrete scenarios

When a relationship is being discussed, stress-test it with a specific scenario that probes the boundary. "A lesson moves to a different section mid-course — does its materialized path change?" Edge cases are where fuzzy models break; force precision there.

Cross-reference with code

When the user states how something works, check whether the code agrees (Grep/Glob/Read). If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

Write it down inline

The moment a term or decision crystallizes, write it — don't defer to an "update docs" step that never happens:

• New/changed term → update CONTEXT.md per CONTEXT-FORMAT.md.
• A decision with trade-offs that future readers will question → write an ADR per ADR-FORMAT.md. For drafting a longer ADR, delegate to the docs-writer agent, then review it yourself before it lands — the agent never commits; if ADRs are the committed category (profile → Artifact git policy), hand the user the commit command to run.

Output

After the session, report:

• Glossary changes — terms added/changed/retired in CONTEXT.md (with the _Avoid_ synonyms).
• ADRs written — docs/adr/NNNN-<slug>.md paths and their one-line decisions.
• Open ambiguities — terms still unresolved, flagged for the user (mirror the "Flagged ambiguities" section in CONTEXT.md).

Hard rules

• Write inline, not later. Capture each term/decision the moment it's settled; an unrecorded model decays back into jargon.
• One term per concept. Canonical term + _Avoid_ synonyms. Consistency is the whole payoff.
• One model per context; rename the slices. When one word carries the whole domain — the class everything hangs off, its fields and status enum drawn from four concerns — the fix is not one definition wide enough to cover them all. Give each context its own model with only the fields its rules need, and rename each to what it is there: fulfilment sees a Ticket, the courier side a Delivery. The name is the test — a slice you cannot name on its own is not a separate context, and collapses back. Record the price under Relationships: those models must now be kept consistent with each other.
• Lazy files. No empty CONTEXT.md/docs/adr/ — create on first real content.
• Don't touch app code. This skill writes CONTEXT.md and ADRs only; renaming code to match the glossary is /refactor's job.
• Ground in code. A glossary term that contradicts the codebase is a bug in one of them — surface it, don't paper over it.

See also

• /grill & /grill-with-docs — a grilling session is where most terms crystallize; run this skill alongside it to capture them. (/analyst also feeds terms here.)
• /codebase-design — its glossary (Module/Seam/Adapter…) is the design vocabulary; this is the domain vocabulary. Both keep the language tight.
• CONTEXT-FORMAT.md · ADR-FORMAT.md — the two formats.