Ubiquitous Language

---
name: ubiquitous-language
description: Extract a domain glossary from the current dialogue; flag ambiguities, propose canonical terms, persist to `UBIQUITOUS_LANGUAGE.md`. Trigger when the user is hardening domain terminology, building a glossary, or fresh domain concepts surface in conversation without documented language.
---

Mine the live conversation for domain-relevant nouns, verbs, and concepts; resolve synonyms and overloaded terms into a canonical, opinionated glossary. Persist the result to `UBIQUITOUS_LANGUAGE.md` so subsequent sessions inherit the same vocabulary. Re-invocation refines the file in place rather than overwriting.

When a candidate term collides with usage already present in the codebase, dispatch an Explore agent (`fd`-first discovery, `git grep`/`ast-grep` content search) to confirm the dominant naming before recommending a winner. The user supplies domain intent; the codebase supplies factual usage.

**Modality vs adjacent skills:** This skill *extracts* glossary from raw conversation when no documented domain language exists yet. *Domain-model grilling* *grills* a plan against an already-documented `CONTEXT.md`/ADRs. Pick `ubiquitous-language` when you are creating the artifact; pick the grilling workflow when you are stress-testing one. The two compose: build the glossary here, then promote stable terms into `CONTEXT.md` and let the grilling workflow defend it thereafter.

## Process

1. Scan the dialogue for domain-relevant nouns, verbs, and concepts. Skip generic programming nouns (array, function, endpoint) unless they carry domain weight.
2. Identify three failure modes: same word for different concepts (ambiguity), different words for the same concept (synonyms), vague or overloaded terms.
3. Propose canonical terms with explicit aliases-to-avoid. Be opinionated — pick one winner per concept and justify briefly.
4. Persist `UBIQUITOUS_LANGUAGE.md` to the working directory using the format in `references/UBIQUITOUS-LANGUAGE-FORMAT.md`.
5. Emit a short inline summary of additions, renames, and flagged ambiguities so the user can react in-thread.

## Rules

- One sentence per definition. Define what the term *is*, not what it *does*.
- Group terms into multiple tables when natural clusters exist (subdomain, lifecycle, actor). Force no grouping when a single cohesive table reads cleanly.
- Express relationships with bold term names and explicit cardinality where obvious (`exactly one`, `one or more`, `optional`).
- Flagged ambiguities require a recommendation, not a question. The skill resolves; the user overrides.
- Treat module and class identifiers as glossary candidates only when they carry domain meaning. Prefer abstract domain terms over implementation aliases.
- Include an example dialogue (3–5 exchanges) demonstrating the terms used precisely. The dialogue clarifies boundaries between adjacent concepts.

## Re-invocation

When invoked again in the same conversation:

1. Read the existing `UBIQUITOUS_LANGUAGE.md`.
2. Incorporate new terms surfaced since the last pass.
3. Update definitions when shared understanding has shifted; preserve the old wording in commit history rather than the file body.
4. Re-flag any new ambiguities; demote resolved ambiguities to a closed note or remove them once the glossary stabilises.
5. Refresh the example dialogue so it exercises the latest term set.

## Reference materials

- `references/UBIQUITOUS-LANGUAGE-FORMAT.md` — table layout, relationship syntax, dialogue template, flagged-ambiguities format. Language-agnostic.