Domain Glossary

Principle

Enterprise systems accumulate terminology debt: the same concept called different names across teams, specs, and code. Synonym drift corrupts search, work-item labeling, and cross-spec consistency. A shared canonical glossary reduces misunderstanding and improves spec-to-code traceability.

Operations

This skill has two modes: extract (build or update a glossary) and validate (check an artifact against the glossary).

1. Extract: Build or Update the Glossary

When to Extract

Extract Procedure

1. Check for existing glossary: Read docs/domain/GLOSSARY.md (or create from template if it does not exist)
2. Scan sources for domain-relevant nouns, verbs, and concepts:
   • Conversation context
   • Spec files (docs/features/**/spec.md)
   • Envisioning documents (docs/envisioning/*.md)
   • ADRs (docs/architecture/decisions/*.md)
   • Code (class names, module names, API endpoints) via codebase search
3. Identify problems:
   • Same word used for different concepts (ambiguity)
   • Different words used for the same concept (synonyms)
   • Vague or overloaded terms
   • Terms in code that differ from terms in specs
4. Propose canonical terms: be opinionated; pick the best term and list others as aliases to avoid
5. Write or update docs/domain/GLOSSARY.md using the format below
6. Present summary inline in the conversation

Glossary Format

# Domain Glossary

## [Domain Group]

| Term | Definition | Status | Aliases to avoid |
|------|-----------|--------|-----------------|
| **[Term]** | [One sentence: what it IS, not what it does] | [Established/Proposed/Contested] | [Synonyms to avoid] |

## Relationships

- A **[Term A]** belongs to exactly one **[Term B]**
- A **[Term C]** produces one or more **[Term D]**

## Flagged Ambiguities

- "[word]" was used to mean both **[Term X]** and **[Term Y]**. These are distinct concepts: [explanation of the difference and recommended usage].

Rules for Extraction

• Be opinionated: when multiple words exist for the same concept, pick the best one and list the others as aliases to avoid
• Flag conflicts explicitly with a clear recommendation
• Only include terms relevant for domain experts; skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning
• Keep definitions tight: one sentence maximum; define what it IS, not what it does
• Show relationships with bold term names and express cardinality where obvious
• Group terms into multiple tables when natural clusters emerge (by subdomain, lifecycle, or actor)
• Create files lazily: only create GLOSSARY.md when the first terms are resolved; do not bloat new projects

Confidence Levels

Mark contested terms in the Flagged Ambiguities section until resolved.

2. Validate: Check Artifact Against Glossary

When to Validate

…