ubiquitous-language

Ubiquitous Language

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

Process

1. Scan the conversation, looking for domain-relevant nouns, verbs, and concepts
2. Identify problems：
   • the same word is used for different concepts (ambiguity)
   • different words are used for the same concept (synonyms)
   • vague or overloaded terms
3. Propose a canonical glossary, stay opinionated about term choices
4. Write to UBIQUITOUS_LANGUAGE.md, using the following format in the working directory
5. Output a summary, summarize inline in the conversation

Output Format

Write a UBIQUITOUS_LANGUAGE.md file, structured as follows:

# 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.
• Flag conflicts explicitly. If a term is used ambiguously in the conversation, point it out in the "Flagged ambiguities" section and give a clear recommendation.
• Only include terms relevant for domain experts. Skip module or class names unless they are meaningful in the domain language.
• Keep definitions tight. At most one sentence. Define what it is, not what it does.
• Show relationships. Use bold term names, and express cardinality when obvious.
• Only include domain terms. Skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning.
• Group terms into multiple tables, use them when natural clusters emerge (e.g., by subdomain, lifecycle, or actor). Each group has its own heading and table. If all terms belong to one cohesive domain, one table is enough; do not force grouping.
• Write an example dialogue. Write a short dialogue between a dev and a domain expert (3-5 exchanges) showing how the terms interact naturally. The dialogue should clarify the boundaries of related concepts and demonstrate precise use of terms.

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 called again in the same conversation:

1. Read the existing UBIQUITOUS_LANGUAGE.md
2. Merge new terms from subsequent discussion
3. Update definitions if the understanding evolves
4. Re-flag any new ambiguities
5. Rewrite the example dialogue to incorporate new terms