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

Validate Procedure

1. Read docs/domain/GLOSSARY.md
   • If file does not exist, skip validation (no glossary yet)
2. Scan the artifact for domain terms
3. For each term found:
   • If it matches a canonical term: OK
   • If it matches an "alias to avoid": flag as terminology drift
   • If it is a domain-relevant term not in the glossary: suggest adding it
4. Report findings:

Terminology check: [artifact]

Drift detected:
- "[alias]" used in [location] — canonical term is **[Term]**

New terms (not in glossary):
- "[new term]" — suggest adding with definition: [proposed definition]

No issues: [count] terms checked, all consistent

3. Code Cross-Reference

When validating code (called from devsquad.review.code):

1. Search for class names, module names, and API endpoints that represent domain concepts
2. Compare against the glossary:
   • Class UserAccount when glossary says Customer: flag as translation smell
   • API endpoint /api/clients when glossary says Customer: flag as inconsistency
3. Do not flag internal implementation names (private variables, utility functions) unless they represent domain concepts exposed in public interfaces
4. Exempt intentional translation boundaries: anti-corruption layers, legacy database schemas, vendor API contracts, and external system adapters may use different terms by design. If a mismatch is at a known boundary, note it but do not flag as drift.

Anti-patterns

• Do not create a glossary for projects with a single bounded context and fewer than 5 domain terms (overhead exceeds value)
• Do not block delivery for terminology drift (flag it, do not enforce)
• Do not capture generic technical terms ("database", "API", "service") unless they have project-specific meaning
• Do not override terms that the team has explicitly chosen, even if another term seems "better"
• Do not duplicate definitions that already exist in accepted ADRs