Ubiquitous Language
Upstream: Adapted from mattpocock/skills/ubiquitous-language. Concept from Eric Evans, Domain-Driven Design.
Extract and formalize domain terminology from the current conversation into a consistent glossary stored at product-docs/UBIQUITOUS_LANGUAGE.md. The same vocabulary is used by domain experts, the user, and the AI — both in planning docs (PRD, JTBD, discovery, tech-decomposition) and in code.
When called from task work, resolve the repository and task with
../setup/references/task-context.md. Context-reading calls from
/nf, /product, and /ct are load-only. Write the glossary only for an explicit update request
or an authorized post-grill update, then link the result from the task record when relevant.
Classify the invocation before writing. A caller's context-reading request is read-only loading. An
explicit request to build/update the project glossary or define its domain terms authorizes
the glossary update; an authorized post-grill caller may do the same. An explanatory request
without that update intent returns proposed terms without writing.
When this fires
/nf Step 0: load existing glossary so discovery questions and the discovery doc use canonical terms.
/nf Step 4 → Step 5 transition: after the grill round, update glossary with new terms before writing the discovery doc.
/product Step 0 and after Step 4 grill: same pattern — load before interview, update before writing PRD/JTBD.
/ct context reading: reuse established project terms from the task's relevant inputs.
- Manual update invocation: when the user explicitly asks to harden terminology, define
domain terms in the project glossary, or build/update the glossary. If the user only asks
an explanatory terminology question, return a proposal without writing.
Process
Load-only branch (context reading)
- Read existing glossary at
product-docs/UBIQUITOUS_LANGUAGE.md (if it exists) and
report its current canonical terms. Stop here. Do not scan, merge, rewrite, or update the
example dialogue for a load-only call.
Build/update branch (explicit request or authorized post-grill call)
- Read existing glossary at
product-docs/UBIQUITOUS_LANGUAGE.md (if it exists). Hold
its content in memory — do NOT use Edit/section-patching. The file is small; the safe path
is read → merge in memory → overwrite.
- Scan the relevant scope for domain-relevant nouns, verbs, and concepts:
- Current conversation
- The active task's PRD / JTBD / discovery doc
- Source code only when terms are ambiguous and the code resolves them
- Identify problems:
- Same word used for different concepts (ambiguity)
- Different words used for the same concept (synonyms)
- Vague or overloaded terms
- Merge in memory: combine existing entries with new findings. Preserve every existing term unless evidence shows it's wrong; revise definitions that have sharpened. Add newly discovered terms. Update "Flagged ambiguities" with anything resolved.
- When the update branch is authorized, ensure the parent directory exists:
mkdir -p product-docs/ (the directory is repo-level, alongside .claude/, and may not
exist on a fresh repo).
- When the update branch is authorized, write the full merged glossary to
product-docs/UBIQUITOUS_LANGUAGE.md, fully overwriting the prior file.
- Output a summary inline so the caller (
/nf, /product, /ct) can paste it into its doc.
Output format
product-docs/UBIQUITOUS_LANGUAGE.md:
# Ubiquitous Language
> Domain terms used across PRDs, JTBDs, discovery docs, technical plans, and code. Read during relevant context gathering; update via `/ubiquitous-language` when authorized.
## [Subdomain or lifecycle name]
| Term | Definition | Aliases to avoid |
| ----------- | ------------------------------------------------------- | --------------------- |
| **Order** | A customer's request to purchase one or more items | Purchase, transaction |
| **Invoice** | A request for payment sent 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."
## Flagged ambiguities
- "account" was used to mean both **Customer** and **User** — these are distinct: a **Customer** places orders, while a **User** is an authentication identity.
Rules
- Be opinionated. When multiple words exist for the same concept, pick one and list the others as aliases to avoid.
- Flag conflicts explicitly. If a term is used ambiguously, call it out in "Flagged ambiguities" with a recommendation.
- Only domain terms. Skip generic programming concepts (array, function, endpoint) and skip the names of modules or classes unless they have meaning in the domain language.
- Tight definitions. One sentence max. Define what it IS, not what it does.
- Show relationships. Use bold term names; express cardinality where obvious.
- Group into multiple tables when natural clusters emerge (subdomain, lifecycle, actor). One table is fine if the domain is cohesive.
- Write an example dialogue. A short conversation (3-5 exchanges) between a dev and a domain expert that uses the terms precisely. The dialogue clarifies boundaries between related concepts.
- No file paths or code snippets. This is a domain document, not an implementation reference.
Re-running
When invoked again in the same conversation, follow the invocation branch:
- Step 0 load: reread and report the existing
UBIQUITOUS_LANGUAGE.md; do not rewrite it.
- Explicit build/update or authorized post-grill update: read the existing file,
incorporate new terms, update definitions and ambiguities, and rewrite the example dialogue
before the authorized full-file write.
Return to caller
After writing/updating the file, return a compact summary so /nf, /product, or /ct can reference it without re-reading the file:
- Terms added: [list]
- Terms revised: [list]
- Ambiguities flagged: [list]
- Suggested canonical phrasing for the upcoming doc: [1-3 examples]
1---2name: ubiquitous-language3description: >-4 Build or update a DDD-style ubiquitous language glossary when the user explicitly asks to5 define domain terms, build/update the project glossary, or harden terminology. For /nf,6 /product, or /ct context-reading calls, load and report the glossary; for authorized post-grill7 updates, merge and write it. Do not write for a load-only or explanatory request. NOT for8 architectural vocabulary (use /architecture-language).9metadata:10 source: https://skillmd.com/skills/alexandrbasis/ubiquitous-language11---1213# Ubiquitous Language1415> **Upstream**: Adapted from [mattpocock/skills/ubiquitous-language](https://github.com/mattpocock/skills/blob/main/ubiquitous-language/SKILL.md). Concept from Eric Evans, *Domain-Driven Design*.1617Extract and formalize domain terminology from the current conversation into a consistent glossary stored at `product-docs/UBIQUITOUS_LANGUAGE.md`. The same vocabulary is used by domain experts, the user, and the AI — both in planning docs (PRD, JTBD, discovery, tech-decomposition) and in code.1819When called from task work, resolve the repository and task with20[`../setup/references/task-context.md`](../setup/references/task-context.md). Context-reading calls from21`/nf`, `/product`, and `/ct` are load-only. Write the glossary only for an explicit update request22or an authorized post-grill update, then link the result from the task record when relevant.2324Classify the invocation before writing. A caller's context-reading request is read-only loading. An25explicit request to build/update the project glossary or define its domain terms authorizes26the glossary update; an authorized post-grill caller may do the same. An explanatory request27without that update intent returns proposed terms without writing.2829## When this fires3031- **`/nf` Step 0**: load existing glossary so discovery questions and the discovery doc use canonical terms.32- **`/nf` Step 4 → Step 5 transition**: after the grill round, update glossary with new terms before writing the discovery doc.33- **`/product` Step 0** and **after Step 4 grill**: same pattern — load before interview, update before writing PRD/JTBD.34- **`/ct` context reading**: reuse established project terms from the task's relevant inputs.35- **Manual update invocation**: when the user explicitly asks to harden terminology, define36 domain terms in the project glossary, or build/update the glossary. If the user only asks37 an explanatory terminology question, return a proposal without writing.3839## Process4041### Load-only branch (context reading)42431. **Read existing glossary** at `product-docs/UBIQUITOUS_LANGUAGE.md` (if it exists) and44 report its current canonical terms. Stop here. Do not scan, merge, rewrite, or update the45 example dialogue for a load-only call.4647### Build/update branch (explicit request or authorized post-grill call)48491. **Read existing glossary** at `product-docs/UBIQUITOUS_LANGUAGE.md` (if it exists). Hold50 its content in memory — do NOT use Edit/section-patching. The file is small; the safe path51 is read → merge in memory → overwrite.522. **Scan the relevant scope** for domain-relevant nouns, verbs, and concepts:53 - Current conversation54 - The active task's PRD / JTBD / discovery doc55 - Source code only when terms are ambiguous and the code resolves them563. **Identify problems**:57 - Same word used for different concepts (ambiguity)58 - Different words used for the same concept (synonyms)59 - Vague or overloaded terms604. **Merge in memory**: combine existing entries with new findings. Preserve every existing term unless evidence shows it's wrong; revise definitions that have sharpened. Add newly discovered terms. Update "Flagged ambiguities" with anything resolved.615. **When the update branch is authorized**, ensure the parent directory exists:62 `mkdir -p product-docs/` (the directory is repo-level, alongside `.claude/`, and may not63 exist on a fresh repo).646. **When the update branch is authorized**, write the full merged glossary to65 `product-docs/UBIQUITOUS_LANGUAGE.md`, fully overwriting the prior file.667. **Output a summary** inline so the caller (`/nf`, `/product`, `/ct`) can paste it into its doc.6768## Output format6970`product-docs/UBIQUITOUS_LANGUAGE.md`:7172```md73# Ubiquitous Language7475> Domain terms used across PRDs, JTBDs, discovery docs, technical plans, and code. Read during relevant context gathering; update via `/ubiquitous-language` when authorized.7677## [Subdomain or lifecycle name]7879| Term | Definition | Aliases to avoid |80| ----------- | ------------------------------------------------------- | --------------------- |81| **Order** | A customer's request to purchase one or more items | Purchase, transaction |82| **Invoice** | A request for payment sent after delivery | Bill, payment request |8384## People8586| Term | Definition | Aliases to avoid |87| ------------ | ------------------------------------------- | ---------------------- |88| **Customer** | A person or organization that places orders | Client, buyer, account |89| **User** | An authentication identity in the system | Login, account |9091## Relationships9293- An **Invoice** belongs to exactly one **Customer**94- An **Order** produces one or more **Invoices**9596## Example dialogue9798> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"99> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."100101## Flagged ambiguities102103- "account" was used to mean both **Customer** and **User** — these are distinct: a **Customer** places orders, while a **User** is an authentication identity.104```105106## Rules107108- **Be opinionated.** When multiple words exist for the same concept, pick one and list the others as aliases to avoid.109- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a recommendation.110- **Only domain terms.** Skip generic programming concepts (array, function, endpoint) and skip the names of modules or classes unless they have meaning in the domain language.111- **Tight definitions.** One sentence max. Define what it IS, not what it does.112- **Show relationships.** Use bold term names; express cardinality where obvious.113- **Group into multiple tables** when natural clusters emerge (subdomain, lifecycle, actor). One table is fine if the domain is cohesive.114- **Write an example dialogue.** A short conversation (3-5 exchanges) between a dev and a domain expert that uses the terms precisely. The dialogue clarifies boundaries between related concepts.115- **No file paths or code snippets.** This is a domain document, not an implementation reference.116117## Re-running118119When invoked again in the same conversation, follow the invocation branch:120121- **Step 0 load:** reread and report the existing `UBIQUITOUS_LANGUAGE.md`; do not rewrite it.122- **Explicit build/update or authorized post-grill update:** read the existing file,123 incorporate new terms, update definitions and ambiguities, and rewrite the example dialogue124 before the authorized full-file write.125126## Return to caller127128After writing/updating the file, return a compact summary so `/nf`, `/product`, or `/ct` can reference it without re-reading the file:129130- Terms added: [list]131- Terms revised: [list]132- Ambiguities flagged: [list]133- Suggested canonical phrasing for the upcoming doc: [1-3 examples]