ddd-glossary-gen

Ubiquitous Language Glossary

Extract and normalize domain terminology from the current conversation, form a consistent glossary, and save it as a local file.

Process

1. Scan the conversation content, identifying domain-related nouns, verbs, and concepts
2. Identify problems：
   • The same word is used for different concepts (ambiguity)
   • Different words refer to the same concept (synonym redundancy)
   • Terms with vague meanings or overly broad scope
3. Propose a canonical glossary, giving clear recommendations for term choices
4. Write to UBIQUITOUS_LANGUAGE.mdin the working directory, in the following format
5. Output a summary in the conversation

Output Format

Generate a UBIQUITOUS_LANGUAGE.md file with the following 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 multiple words exist for the same concept, choose one best term and list the rest as "aliases to avoid".
• Mark conflicts explicitly. If a term is used ambiguously in the conversation, point it out in the "Flagged Ambiguities" section and give a clear recommendation.
• Include only terms that domain experts care about. Skip module names or class names unless they have real meaning in the domain language.
• Keep definitions concise. At most one sentence. Define what itis, not what it does.
• Show relationships. Use bold term names and mark cardinality relationships where obvious.
• Include only domain terms. Skip general programming concepts (arrays, functions, interfaces, etc.) unless they have special meaning in the domain.
• Group terms into multiple tableswhen natural categories emerge (for example, grouped by subdomain, lifecycle, or role). Each group has its own heading and table. If all terms belong to the same cohesive domain, one table is enough—do not force grouping.
• Write an example dialogue. A short dialogue (3-5 exchanges) between a developer and a domain expert, showing how these terms work together in natural communication. The dialogue should clarify the boundaries between related concepts and demonstrate precise usage of the terms.

Example Dialogue

Developer: "How can I test the sync service？"

Domain Expert: "Use the filesystem layer instead of the Docker layer. It implements the same sandbox service interface, just using a local directory as the sandbox。"

Developer: "Then will sync-in still create bundle and then unpack it?"

Domain Expert: "Exactly.sync service It doesn't know which layer it is communicating with. It calls exec and copyIn——file system layer only executes these as local shell commands."

Re-run

When called again in the same conversation:

1. Read the existing UBIQUITOUS_LANGUAGE.md
2. Incorporate new terms that appear in subsequent discussion
3. Update definitions if the understanding changes
4. Re-mark newly discovered ambiguities
5. Rewrite example dialogues to incorporate new terms