Ubiquitous Language

Audit Mode

1. Read existing ubiquitous_language.md. If it does not exist, tell the user to run the default mode first and stop.
2. Build a search list from the glossary — all canonical terms, all aliases-to-avoid, and all deprecated terms.
3. Walk the codebase — grep for every alias-to-avoid and deprecated term across source files, comments, documentation, and config files.
4. Report inline with:
   • Deprecated terms still found in code (term, recommended replacement, file count)
   • Aliases-to-avoid found in code (which canonical term to use instead, file count)
   • Glossary terms not found anywhere in the codebase (potentially unused or misnamed)
5. Do not modify ubiquitous_language.md. Audit is read-only and report-only. The user decides what to act on.

Output Format

Write ubiquitous_language.md following this concrete example:

# Ubiquitous Language

## Order Lifecycle

| Term | Context | Definition | Rationale | Aliases to avoid |
| --- | --- | --- | --- | --- |
| **Order** | Sales | A customer's request to purchase one or more items | Chosen over "purchase" — purchase implies completed payment | Purchase, transaction |
| **Order** | Fulfillment | A directive to warehouse to pick and ship items | Same word, different bounded context | Shipment request |
| **Invoice** | Billing | A request for payment sent to a customer after delivery | "Bill" is informal and ambiguous with legislative bills | Bill, payment request |

## People

| Term | Context | Definition | Rationale | Aliases to avoid |
| --- | --- | --- | --- | --- |
| **Customer** | Global | A person or organization that places orders | "Client" is ambiguous with API clients | Client, buyer, account |
| **User** | Auth | An authentication identity in the system | Distinct from Customer — a User may not be a Customer | Login, account |

## Relationships

- An **Order** (Sales) belongs to exactly one **Customer**
- An **Order** (Sales) produces one or more **Invoices** (Billing)
- A **User** (Auth) may or may not map to a **Customer**

## 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** confirms the **Order**. 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: a **Customer** places orders, a **User** is an auth identity that may or may not represent a **Customer**.

## Deprecated Terms

- `subscription` → use **Membership** — subscriptions imply recurring billing, ours are fixed-term
- `client` → use **Customer** (domain) or **API Consumer** (technical) — "client" is ambiguous across both

Column Definitions

• Term: Bold canonical name for the domain concept.
• Context: The bounded context where this definition applies. Use "Global" when the term means the same thing everywhere.
• Definition: One sentence max. Define what it IS, not what it does.
• Rationale: Why this canonical term was chosen over alternatives. Especially important for contentious or non-obvious choices.
• Aliases to avoid: Synonyms or conflicting terms that should not be used for this concept in this context.

Section Rules

• Glossary tables: Group by natural clusters — subdomain, lifecycle, actor type. Each group gets its own H2 heading and table. If all terms belong to one cohesive domain, one table is fine. Do not force artificial groupings.
• Relationships: Use bold term names with cardinality. Include bounded context in parentheses when a term has context-specific definitions.
• Example dialogue: 3-5 exchanges between a dev and domain expert. Show terms interacting naturally, clarify boundaries between related concepts, demonstrate precise usage.
• Flagged ambiguities: Terms used inconsistently in conversation, with clear recommendation.
• Deprecated terms: Terms actively in use that should be migrated. Format: `old_term` → use **Canonical Term** — reason.

Rules

• 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 used ambiguously, call it out in "Flagged ambiguities" with a clear recommendation.
• Only domain terms. Skip module or class names unless they have meaning in the domain language.
• Tight definitions. One sentence max. What it IS, not what it does.
• Assign bounded context. Use "Global" when a term means the same thing everywhere. When the same word means different things in different parts of the system, create separate rows with different Context values.
• Document rationale. Especially for contentious or non-obvious term choices. This prevents future debates.
• Populate deprecated terms when codebase grep reveals aliases-to-avoid or old terminology actively in use.
• Group naturally. Multiple tables when clusters emerge, one table when they don't.
• Write example dialogue. 3-5 exchanges showing terms used precisely in context.

Re-running

When invoked again in default mode:

1. Read the existing ubiquitous_language.md
2. Incorporate new terms from the conversation
3. Update definitions if understanding has evolved — never silently drop existing terms
4. Merge bounded contexts — split "Global" terms into context-specific rows when needed
5. Re-flag ambiguities — update or resolve previous flags
6. Rewrite example dialogue to incorporate new terms
7. Update deprecated terms if new aliases-to-avoid are found in the codebase