Skill Tracer
Skills › Skills For Real Engineers › domain-modeling

domain-modeling

skill · 74 lines · MIT · skills/engineering/domain-modeling/SKILL.md

The facts

Its description

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

The description the agent reads to decide when to use it.

From its settingsline 3

When it starts

The agent picks this skill when the conversation turns to the project's own vocabulary or its recorded decisions — arguing over what a term should mean, or wanting to write or edit a GLOSSARY.md or an ADR — rather than when it is merely reading a glossary for vocabulary.

Things a person might say (the model's guesses)

  • “I keep saying 'account' — should that be Customer or User?”
  • “Let's write an ADR for using Postgres as the write model.”
  • “Can we add 'cancellation' to the glossary?”

A model's summary of when it is used.

A model's reading

Files it mentions

./GLOSSARY-FORMAT.md, ./ADR-FORMAT.md

Files the text names, such as ones to read or write. Found by matching words, so treat them as pointers.

Found by matching wordsline 62 line 74

What leads to it

Other skills that hand off to this one, call it, require it or offer it instead, as a model read them.

A model's reading

Licence

MIT, from LICENSE

The terms its author shares it under, which let it be shown here.

From the repositorylicence text
Other files in this skill (3) Close

The text

Open on GitHub

Most marks come from matching words in the file, so treat them as pointers.

1---
2name: domain-modeling
3description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
4---
5
6# Domain Modeling
7
8Actively 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 crystallise. (Merely *reading* `GLOSSARY.md` for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
9

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 crystallise. (Merely reading GLOSSARY.md for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)

Raw lines 1 to 9
10## File structure
12Most repos have a single context:
14```
16├── GLOSSARY.md
17├── docs/
18│ └── adr/
19│ ├── 0001-event-sourced-orders.md
20│ └── 0002-postgres-for-write-model.md
21└── src/
22```
24If a `GLOSSARY-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
26```
28├── GLOSSARY-MAP.md
29├── docs/
30│ └── adr/ ← system-wide decisions
31├── src/
32│ ├── ordering/
33│ │ ├── GLOSSARY.md
34│ │ └── docs/adr/ ← context-specific decisions
35│ └── billing/
36│ ├── GLOSSARY.md
37│ └── docs/adr/
38```
40Create files lazily: only when you have something to write. If no `GLOSSARY.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.

File structure

Most repos have a single context:

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

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

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

Create files lazily: only when you have something to write. If no GLOSSARY.md exists, create one when the first term is resolved. If no docs/adr/ exists, create it when the first ADR is needed.

Raw lines 10 to 41
42## During the session

During the session

Raw lines 42 to 43
44### Challenge against the glossary
46When 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?"

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?"

Raw lines 44 to 47
48### Sharpen fuzzy language
50When 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."

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."

Raw lines 48 to 51
52### Discuss concrete scenarios
54When 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.

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.

Raw lines 52 to 55
56### Cross-reference with code
58When 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?"

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?"

Raw lines 56 to 59
60### Update GLOSSARY.md inline
62When 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-FORMAT.md).
64`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.

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.

Raw lines 60 to 65
Reads a file ./GLOSSARY-FORMAT.md :62
66### Offer ADRs sparingly
68Only offer to create an ADR when all three are true:
701. **Hard to reverse**: the cost of changing your mind later is meaningful
712. **Surprising without context**: a future reader will wonder "why did they do it this way?"
723. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
74If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

Offer ADRs sparingly

Only offer to create an ADR 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 the ADR. Use the format in ADR-FORMAT.md.

Raw lines 66 to 74
Reads a file ./ADR-FORMAT.md :74

From mattpocock/skills at 4ae2317, 2026-10-31. Skills read by DeepSeek V4.1 Flash on 2026-11-04. Summary and techniques by Claude Opus 5.5 on 2026-11-06.