| name | ubiquitous-language |
| description | Extract and save a DDD glossary, flag ambiguities, and propose canonical terms. Use when defining domain language or a shared vocabulary. |
Ubiquitous Language
Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to a local file.
Process
- Scan the conversation for domain-relevant nouns, verbs, and concepts
- Identify problems:
- Same word used for different concepts (ambiguity)
- Different words used for the same concept (synonyms)
- Vague or overloaded terms
- Propose a canonical glossary with opinionated term choices
- Write to
raw/UBIQUITOUS_LANGUAGE.md in the working directory using the format below. If content is split into sections, write each section to raw/UBIQUITOUS_LANGUAGE/{section-name}.md and document the folder structure in raw/UBIQUITOUS_LANGUAGE.md.
- Output a summary inline in the conversation
Output Format
Write a raw/UBIQUITOUS_LANGUAGE.md file with this structure:
# Ubiquitous Language
## Order lifecycle
| Term | Definition | Aliases to avoid |
| ----------- | ------------------------------------------------------- | --------------------- |
| **Order** | A customer's request to purchase one or more items | Purchase, transaction |
| **Invoice** | A request for payment sent to a customer after delivery | Bill, payment request |
## People
| Term | Definition | Aliases to avoid |
| ------------ | ------------------------------------------- | ---------------------- |
| **Customer** | A person or organization that places orders | Client, buyer, account |
| **User** | An authentication identity in the system | Login, account |
## Relationships
- An **Invoice** belongs to exactly one **Customer**
- An **Order** produces one or more **Invoices**
## Example dialogue
> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed. A single **Order** can produce multiple **Invoices** if items ship in separate **Shipments**."
> **Dev:** "So if a **Shipment** is cancelled before dispatch, no **Invoice** exists for it?"
> **Domain expert:** "Exactly. The **Invoice** lifecycle is tied to the **Fulfillment**, not the **Order**."
## Flagged ambiguities
- "account" was used to mean both **Customer** and **User** — these are distinct concepts: a **Customer** places orders, while a **User** is an authentication identity that may or may not represent a **Customer**.
Rules
- Be opinionated. Pick the best term when multiple exist for the same concept. List others as aliases to avoid.
- Flag conflicts explicitly. Call out ambiguous usage in "Flagged ambiguities" with a recommendation.
- Keep definitions tight. One sentence max. Define what it IS, not what it does.
- Only include domain terms. Skip module/class names unless they have domain meaning.
- Show relationships. Use bold term names and express cardinality.
- Group terms into tables when natural clusters emerge (by subdomain, lifecycle, or actor). One table is fine if all terms are cohesive — don't force groupings.
- Write example dialogue. 3-5 exchanges between dev and domain expert demonstrating terms in action.
Example dialogue
Dev: "How do I test the sync service without Docker?"
Domain expert: "Provide the filesystem layer instead of the Docker layer. It implements the same Sandbox service interface but uses a local directory as the sandbox."
Dev: "So sync-in still creates a bundle and unpacks it?"
Domain expert: "Exactly. The sync service doesn't know which layer it's talking to. It calls exec and copyIn — the filesystem layer just runs those as local shell commands."
Re-running
When invoked again in the same conversation:
- Read the existing
raw/UBIQUITOUS_LANGUAGE.md
- Incorporate any new terms from subsequent discussion
- Update definitions if understanding has evolved
- Re-flag any new ambiguities
- Rewrite the example dialogue to incorporate new terms
