| name | domain-modeling |
| description | Actively build and sharpen a project's domain model — challenge fuzzy or overloaded terms against a glossary, stress-test with edge cases, and maintain CONTEXT.md as the source of truth for a ubiquitous language.
Use when the user wants to pin down domain terminology, resolve a naming conflict, define a ubiquitous language, or when another skill needs to produce or sharpen the domain model. Triggers on "what should we call this", "domain model", "ubiquitous language", "define these terms", "update CONTEXT.md".
|
| allowed-tools | Read, Write, Edit, Grep, Glob |
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 CONTEXT.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 CONTEXT.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:
- Honour an explicit
[company] / [path] argument
- Fall back to
workspace/threads/handoff.json .company
- Fall back to cwd inference via
companies/manifest.yaml
- 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>/CONTEXT.md and <repo>/docs/adr/. These conventions are already HQ-adopted: /architect and /diagnose read <repo>/CONTEXT.md for vocabulary and <repo>/docs/adr/ for decisions.
File structure
Most repos have a single context:
<repo>/
├── CONTEXT.md
├── docs/
│ └── adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
If a CONTEXT-MAP.md exists at the repo root, the repo has multiple contexts. The map points to where each one lives:
<repo>/
├── CONTEXT-MAP.md
├── docs/
│ └── adr/ ← system-wide decisions
├── src/
│ ├── ordering/
│ │ ├── CONTEXT.md
│ │ └── docs/adr/ ← context-specific decisions
│ └── billing/
│ ├── CONTEXT.md
│ └── docs/adr/
Infer which structure applies:
- If
CONTEXT-MAP.md exists, read it to find the contexts.
- If only a root
CONTEXT.md exists, it is a single context.
- If neither exists, create a root
CONTEXT.md lazily when the first term is resolved.
Create files lazily — only when you have something to write. If no CONTEXT.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 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 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 CONTEXT.md inline
When a term is resolved, update CONTEXT.md right there. Don't batch these up — capture them as they happen. Use the format in CONTEXT-FORMAT.md.
CONTEXT.md should be totally devoid of implementation details. Do not treat CONTEXT.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 CONTEXT.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:
- Hard to reverse — the cost of changing your mind later is meaningful.
- Surprising without context — a future reader will wonder "why did they do it this way?"
- 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 CONTEXT.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 CONTEXT.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>/CONTEXT.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.
