v1-shared-language

name	v1-shared-language
description	Use when extracting a domain glossary or canonical terminology from a conversation. Triggers on "build a glossary", "ubiquitous language", or "define the domain terms".

Ubiquitous Language

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

Process

1. Scan the conversation for domain-relevant nouns, verbs, and concepts
2. Identify problems:
   • Same word used for different concepts (ambiguity)
   • Different words used for the same concept (synonyms)
   • Vague or overloaded terms
3. Propose a canonical glossary with opinionated term choices
4. Write to LANGUAGE.md in the working directory using the format below
5. Output a summary inline in the conversation

Output Format

Write a LANGUAGE.md file with this structure:

# 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, pick the best one and list the others as aliases to avoid.
• Flag conflicts explicitly. If a term is used ambiguously in the conversation, call it out in the "Flagged ambiguities" section with a clear recommendation.
• Only include terms relevant for domain experts. Skip the names of modules or classes unless they have meaning in the domain language.
• 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.
• Only include domain terms. Skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning.
• 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 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:

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

Inline term update

The two modes above extract a glossary in a batch — a full scan of the conversation, written or rewritten in one pass. This mode does the opposite: upsert one term the moment it is resolved, without rescanning the conversation or rewriting the file. It exists so a stateful interview (see v1-interview-me's with-docs mode) can record terms as they crystallize instead of losing them.

Given a single term — its canonical name, one-sentence definition, and optional group and aliases-to-avoid — do exactly this and nothing more:

1. Read LANGUAGE.md if it exists. If it does not, create it with the # Language heading.
2. Find the table for the term's group (create the group heading and a Term | Definition | Aliases to avoid table if that group has none yet).
3. Upsert the single row: if a row for this term exists, update its definition and aliases in place; otherwise append a new row. Match on the canonical term name.
4. Leave every other term, table, relationship, ambiguity note, and the example dialogue untouched. Do not rewrite the file, re-scan the conversation, or regenerate the example dialogue.

Keep the same tight, opinionated definition style as the batch mode (one sentence, define what it IS). The upsert is idempotent: calling it again with an evolved definition updates the row in place rather than duplicating it. Only promote a term inline once it is actually resolved — a term still under discussion is not ready to write.