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

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