ubiquitous-language

Ubiquitous Language

Extract and formalize domain terms from the current conversation, form a consistent glossary, and save it to a local file.

Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to a local file.

Process

Scan the conversationfor domain-related nouns, verbs, and concepts

Scan the conversation for domain-relevant nouns, verbs, and concepts
Identify problems：

Identify problems:
- The same word used for different concepts (ambiguity)
  
  Same word used for different concepts (ambiguity)
- Different words used for the same concept (synonyms)
  
  Different words used for the same concept (synonyms)
- Vague or overloaded terms
  
  Vague or overloaded terms
Propose a canonical glossary, including opinionated term choices

Propose a canonical glossary with opinionated term choices
Write to UBIQUITOUS_LANGUAGE.md, using the following format

Write to UBIQUITOUS_LANGUAGE.md in the working directory using the format below
Output a summary in the conversation

Output a summary inline in the conversation

Output Format

Write a UBIQUITOUS_LANGUAGE.md file with the following structure:

Write a 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. When there are multiple words for the same concept, choose the best one and list the others as aliases to avoid.

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. If a term is ambiguous in the conversation, point it out in the "Flagged ambiguities" section and give a clear recommendation.

Flag conflicts explicitly. If a term is used ambiguously in the conversation, call it out in the "Flagged ambiguities" section with a clear recommendation.
Include only terms relevant to domain experts. Skip the names of modules or classes unless they are meaningful in the domain language.

Only include terms relevant for domain experts. Skip the names of modules or classes unless they have meaning in the domain language.
Keep definitions concise. One sentence at most. Define what it is, not what it does.

Keep definitions tight. One sentence max. Define what it IS, not what it does.
Show relationships. Use bold term names and express cardinality where obvious.

Show relationships. Use bold term names and express cardinality where obvious.
Include only domain terms. Skip general programming concepts (arrays, functions, endpoints) unless they have domain-specific meaning.

Only include domain terms. Skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning.
Group terms into multiple tableswhen natural clusters emerge (for example by subdomain, lifecycle, or actor). Each group has its own heading and table. If all terms belong to a single cohesive domain, one table is enough — do not force grouping.

Group terms into multiple tables when natural clusters emerge (e.g. by subdomain, lifecycle, or actor). Each group gets its own heading and table. If all terms belong to a single cohesive domain, one table is fine — don't force groupings.
Write an example dialogue. A short dialogue (3-5 turns) between a developer and a domain expert, showing how the terms interact naturally. The dialogue should clarify the boundaries between related concepts and demonstrate precise use of the terms.

Write an example dialogue. A short conversation (3-5 exchanges) between a dev and a domain expert that demonstrates how the terms interact naturally. The dialogue should clarify boundaries between related concepts and show terms being used precisely.

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: