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 down the moment a term crystallises. Merely reading GLOSSARY.md for vocabulary is a one-line habit any skill can do (and /architect and /diagnose already do it). This skill is for when you are changing the model, not just consuming it — it is the producer that keeps GLOSSARY.md honest.

Pattern adapted from mattpocock/skills (skills/engineering/domain-modeling), upstream commit 391a270; HQ cross-references and delegation to /adr added.

When this skill vs others

Situation	Skill
Fuzzy, overloaded, or conflicting domain terms; need a ubiquitous language	/domain-modeling (this)
A decision is hard to reverse, surprising, and a real trade-off	hand off to /adr
The architecture (module shape, seams) is the problem, not the vocabulary	/architect
A bug you cannot reliably reproduce or measure	/diagnose

This skill never creates ADRs itself. When a decision qualifies, it hands off to /adr (see "Offer ADRs sparingly").

Step 0 — Resolve company + repo context

Same resolution order the other engineering skills use:

1. Honour an explicit [company] / [path] argument
2. Fall back to workspace/threads/handoff.json .company
3. Fall back to cwd inference via companies/manifest.yaml
4. Last resort: ask the user (one question at a time — see below)

The domain model lives with the code. For a repo under repos/, use <repo>/GLOSSARY.md and <repo>/docs/adr/. These conventions are already HQ-adopted: /architect and /diagnose read <repo>/GLOSSARY.md for vocabulary and <repo>/docs/adr/ for decisions.

File structure

Most repos have a single context:

<repo>/
├── GLOSSARY.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

If a GLOSSARY-MAP.md exists at the repo root, the repo has multiple contexts. The map points to where each one lives:

<repo>/
├── GLOSSARY-MAP.md
├── docs/
│   └── adr/                          ← system-wide decisions
├── src/
│   ├── ordering/
│   │   ├── GLOSSARY.md
│   │   └── docs/adr/                 ← context-specific decisions
│   └── billing/
│       ├── GLOSSARY.md
│       └── docs/adr/

Infer which structure applies:

• If GLOSSARY-MAP.md exists, read it to find the contexts.
• If only a root GLOSSARY.md exists, it is a single context.
• If neither exists, create a root GLOSSARY.md lazily when the first term is resolved.

Create files lazily — only when you have something to write. If no GLOSSARY.md exists, create one when the first term is resolved. When multiple contexts exist, infer which one the current topic relates to; if it is unclear, ask.

During the session

Challenge against the glossary

When the user uses a term that conflicts with the existing language in GLOSSARY.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 vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."

Discuss concrete scenarios

When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.

Cross-reference with code

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

Update GLOSSARY.md inline

When a term is resolved, update GLOSSARY.md right there. Don't batch these up — capture them as they happen. Use the format in GLOSSARY-FORMAT.md.

GLOSSARY.md should be totally devoid of implementation details. Do not treat GLOSSARY.md as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.

One decision at a time

When a term, boundary, or naming choice needs a human call, ask it as a single, focused question and wait for the answer before moving on — the HQ charter's structured one-question-at-a-time discipline. Don't bundle five naming decisions into one wall of text; resolve them one at a time and write each into GLOSSARY.md as it lands. If an AskUserQuestion-style prompt is available in the harness, use it for the pick.

Offer ADRs sparingly — then hand off to /adr

Only offer to record a decision when all three are true:

1. Hard to reverse — the cost of changing your mind later is meaningful.
2. Surprising without context — a future reader will wonder "why did they do it this way?"
3. The result of a real trade-off — there were genuine alternatives and you picked one for specific reasons.

If any of the three is missing, skip it. A naming decision with no trade-off belongs in GLOSSARY.md, not an ADR.

When a decision does qualify, do not write the ADR yourself — hand off to /adr. /adr owns the three-condition gate, the numbering, the target-directory resolution (repo vs company scope), and the file format. Frame the hand-off as: "That's a hard-to-reverse call worth recording — want me to capture it via /adr?" The ADR-FORMAT.md in this folder is reference only for what an ADR looks like; /adr is what produces one.

Cross-references

• /adr — the producer for architectural decisions. This skill detects an ADR-worthy decision and hands off; /adr runs the gate and writes the record.
• /architect — consumes GLOSSARY.md vocabulary when scoring architecture candidates, and surfaces new domain terms back into it inline. Reach for it when the module shape is the problem, not the vocabulary.
• /diagnose — reads <repo>/GLOSSARY.md and <repo>/docs/adr/ when framing a bug; a sharper glossary makes its hypotheses sharper.
• /codebase-design — pairs a crisp ubiquitous language with the module-design pass.
• Pattern source: mattpocock/skills (skills/engineering/domain-modeling), upstream commit 391a270.