ubiquitous-language

name	ubiquitous-language
description	Extracts DDD ubiquitous language glossary, flags ambiguities, saves to UBIQUITOUS_LANGUAGE.md. Triggers: define domain terms, build glossary, harden terminology, DDD, domain model.
user-invocable	true
effort	medium
argument-hint	[domain or context to extract terms from]
allowed-tools	Read, Write, Edit, Grep, Glob

Ubiquitous Language

$ARGUMENTS

Extract and formalize domain terminology into a consistent glossary.

Usage

/ubiquitous-language [domain or context]

What This Command Does

1. Scans conversation for domain-relevant nouns, verbs, and concepts
2. Identifies ambiguities, synonyms, and overloaded terms
3. Proposes canonical glossary with opinionated term choices
4. Writes to UBIQUITOUS_LANGUAGE.md

Process

1. Scan conversation for domain terms
2. Identify problems:
   • Same word used for different concepts (ambiguity)
   • Different words used for same concept (synonyms)
   • Vague or overloaded terms
3. Propose canonical glossary
4. Write to UBIQUITOUS_LANGUAGE.md
5. Output summary inline

Output Format

# Ubiquitous Language

## {Domain Group}

| Term | Definition | Aliases to avoid |
|------|-----------|-----------------|
| **Order** | A customer's request to purchase one or more items | Purchase, transaction |

## Relationships

- An **Invoice** belongs to exactly one **Customer**

## Example dialogue

> **Dev:** "When a **Customer** places an **Order**..."
> **Domain expert:** "..."

## Flagged ambiguities

- "account" was used to mean both **Customer** and **User** — ...

Rules

• MUST be opinionated — pick the best term and list alternatives as aliases to avoid
• MUST flag every ambiguity (one word → two concepts) and every synonym (two words → one concept) with an explicit recommendation
• MUST write tight definitions (one sentence) that define what the term is, not what it does
• NEVER include generic programming concepts (array, function, endpoint, class) — this glossary is for the domain, not the toolchain
• NEVER silently overwrite an existing UBIQUITOUS_LANGUAGE.md — read the current file first, then update incrementally preserving prior decisions
• CRITICAL: show relationships with cardinality ("an Order belongs to exactly one Customer"). Vocabulary without relationships is a word list, not a language.
• MANDATORY: include 3-5 example dialogue exchanges showing correct usage. Abstract glossaries without dialogue rarely get adopted.

Gotchas

• Domain terms often overlap with framework jargon (e.g., "Service" in DDD vs "Service" in Angular). If the framework already claims a term, prefer a domain-specific alternative to avoid collision.
• Stakeholders resist terminology change even when their current terms are ambiguous. "Account" replacing "User" triggers more discussion than expected — plan for negotiation in the example dialogue section.
• Glossaries rot when features ship without updating them. A UBIQUITOUS_LANGUAGE.md last updated 6 months ago is a snapshot, not a source of truth. Flag staleness in the header and re-run this skill periodically.
• Relationships between terms are easy to hand-wave with "related to". Pin down the cardinality (0..1, 1..*, 1..1) — vague relationships produce schema ambiguity later.
• The opinionated canonical choice may contradict marketing or legal language. Note conflicts explicitly rather than hiding them; the domain model and the marketing site can legitimately diverge.

When NOT to Use

• For writing a PRD (full requirements) — use /write-a-prd
• For generating user-facing documentation — use /docs
• For implementation planning — use /plan or /prd-to-plan
• For enforcing language in commit messages or code reviews — use /brand-voice (distinct concern: writing style, not domain terms)
• When the project is a single-developer throwaway — glossary overhead is not justified