domain-modeling

Domain Modeling

Overview

A project's agents are verbose and misaligned when they lack a shared language: the same concept gets three names, one name covers three concepts, and every prompt re-explains what a term means. A tight glossary fixes this — it collapses ambiguity and tokens at once.

Core principle: the glossary is terminology only. One authoritative definition per term, and nothing else. It is never a spec, never an architecture doc, never a scratchpad. The moment an entry carries implementation detail or a design decision, it stops being a glossary and starts rotting.

The glossary lives at {{specs_dir}}/glossary.md.

When to Use

• Defining a product or feature and a term keeps getting used loosely or two ways ([[design-product]], [[understanding-feature-requests]])
• Architecture work surfaces concepts the team has no agreed name for ([[design-architecture]])
• You catch yourself re-explaining the same concept across prompts or docs

Lazy Creation

{{specs_dir}}/glossary.md does not exist until the first term resolves. Do not scaffold an empty file or a placeholder. An empty glossary is sediment; create the file when you have a real first entry, not before.

Process

Capture terms inline, as they crystallize during design and requirements work — never in a batch at the end. Batching loses the context that made the term precise.

1. Capture on crystallization. A concept earns an entry the moment it has a stable, agreed meaning. Write it immediately, in the format below. Do not wait for a "glossary pass."
2. Challenge vague or conflicting language on the spot. When usage drifts, name it: "Your glossary defines X as A, but you're using it as B — which is it?" Resolve to one definition; update the entry or the usage, never both meanings.
3. Stress-test relationships with concrete edge cases. Walk a real scenario at the boundary — empty, zero, expired, two-at-once — and check the definition and its links still hold. If the scenario breaks the entry, the term was underspecified; tighten it.
4. Cross-check terms against the code. Surface contradictions where the code's structures and names disagree with the agreed term. A glossary that contradicts the codebase is worse than none — reconcile the name, the definition, or the code.

Follow the entry format in the sibling. See CONTEXT-FORMAT.md.

Glossary vs. decision

A glossary entry records what a word means, not why a path was chosen. When resolving a term forces a real architectural trade-off, that's a decision record (see the decision-record gate in ${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md), not a glossary entry. Record it in the architecture doc via [[design-architecture]] and link the term to it. Do not narrate the decision inside the definition.

Rationalizations

Excuse	Reality
"I'll add the schema/endpoint so it's all in one place"	That makes it a spec. The glossary holds meaning only; implementation rots the entry out of sync.
"I'll collect all the terms at the end in one pass"	The precision came from the context you had when the term crystallized. Batching loses it.
"Both teams use the word slightly differently — I'll note both"	Two meanings is the bug, not the entry. One authoritative definition; redirect the rest.
"I'll explain why we defined it this way here"	Rationale belongs in the architecture decision record, not the glossary. The definition states what, not why.
"Let me stub an empty glossary so it exists"	Empty file = sediment. Create on the first resolved term.

Red Flags

• An entry contains a table name, function signature, file path, or library choice
• The same concept has two entries under different names
• One entry's definition contradicts how the code names or structures the thing
• You're writing the glossary in a single batch after design is "done"
• An entry argues why a choice was made instead of stating what the term means
• A placeholder or empty glossary.md committed before any term resolved

Verification

• glossary.md exists only because at least one term has resolved; no placeholder entries
• Every entry follows CONTEXT-FORMAT.md (Term, Definition, Relationships, Edge cases; alphabetical)
• No entry contains implementation detail or decision rationale
• Each concept appears exactly once; no synonym has its own definition
• Every term was stress-tested against at least one concrete edge-case scenario
• Terms checked against the code; no name or meaning contradicts the codebase
• Any trade-off uncovered while resolving a term is recorded as an architecture decision (see [[design-architecture]]), not inside the definition