f5ed5657bd
Adds a docs page for every promoted skill that lacked one, following .agents/writing-docs.md and using docs/engineering/to-prd.md as the worked exemplar. Covers all of engineering/ (bar to-prd, already done), productivity/, and misc/. Each page states its load-bearing constraint, its invocation mode and trigger boundary, surfaces the skill's leading word, and routes back to ask-matt so the set forms a connected router with no dead ends. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
3.6 KiB
Quickstart:
npx skills add mattpocock/skills --skill=domain-modeling
npx skills update domain-modeling
What it does
domain-modeling builds and sharpens a project's ubiquitous language as you design — challenging fuzzy terms, stress-testing relationships with concrete scenarios, and writing the glossary and decisions down the moment they crystallise.
The load-bearing constraint: this is the active discipline, not the passive one. Merely reading CONTEXT.md to borrow its vocabulary is a one-line habit any skill can do; this skill is for when you are changing the model — coining a canonical term, catching a contradiction between the code and what you just said, recording a hard-to-reverse decision. And it keeps the glossary clean: CONTEXT.md is a glossary and nothing else — no implementation details, no spec, no scratch pad.
When to reach for it
Type /domain-modeling, or the agent reaches for it automatically when a task fits — when you are pinning down terminology, resolving an overloaded word, or recording an architectural decision.
Reach for it when the words are the problem: two people mean different things by "cancellation", "account" is doing three jobs, or a design conversation keeps snagging on a concept that has never been named precisely. If instead the module's shape is the problem — where the seam goes, how deep the interface is — use codebase-design. If you want the plan itself interrogated before you build, use grilling.
Prerequisites
The skill writes into two places, both created lazily — only once there is something to record. Resolved terms go into CONTEXT.md at the root (or, in a multi-context repo flagged by a CONTEXT-MAP.md, into the per-context CONTEXT.md). Decisions go into docs/adr/. Nothing needs to exist up front; the first resolved term creates the glossary, the first real trade-off creates the ADR.
Glossary vs. ADR
Two artifacts, two different bars:
- The glossary (
CONTEXT.md) captures language. Every time a vague term is made canonical, it's written down inline — not batched — so the shared vocabulary stays current with the conversation. It stays ruthlessly free of implementation detail. - An ADR captures a decision, and the bar is high: offered only when the choice is hard to reverse, surprising without context, and the result of a real trade-off. Miss any one of the three and there is no ADR. This is what keeps
docs/adr/a record of consequential forks rather than a diary.
The move that makes it click: when you state how something works, the skill cross-references the code and surfaces the contradiction — "your code cancels entire Orders, but you just said partial cancellation is possible — which is right?" The language and the code are forced to agree.
Where it fits
domain-modeling is a reach-for-it-anytime standalone that maintains the vocabulary the rest of the work depends on — so it often runs underneath other skills rather than at a fixed step. Its closest neighbour is codebase-design, because a shared language is what lets you name a deep module and its seam precisely; downstream, a settled glossary is exactly what to-prd synthesises into a spec written in the project's own words. When you're unsure which skill or flow fits, ask-matt routes you.