Ubiquitous Language
Write and maintain docs/ai/specs/ubiquitous-language.md: one table of the
domain terms this repository uses, what each means here, and the code
identifiers that carry it. Grill Me and PRD authoring read it when present, so
a term is pinned once and reused instead of re-derived in every interview. In
Codex, use $skill-name syntax for plugin skills.
Ground recommendations
Inspect the tools and skills actually available. Follow the shared
capability-discovery
and grounding contracts.
A term's meaning comes from the code and documents that use it; disclose
uncertainty and do not invent a definition.
Workflow
Read what exists. If docs/ai/specs/ubiquitous-language.md exists,
read it first and treat its rows as settled unless the user reopens one.
Read .specify/memory/constitution.md, the technical roadmaps under
docs/ai/specs/, and any PRD under docs/ for terms already in use.
Scan the repository. Collect candidate terms from module and package
names, exported classes and functions, database tables and columns, API
routes, and README or docs headings. Group names that split the same
concept (Invoice, bill, statement) and names that overload one word
for two concepts.
Propose the table. For each term, write one row: the term, its meaning
in this repository in one sentence, and the identifiers that carry it.
Where the codebase disagrees with itself, propose one term and list the
other spellings under Identifiers so the lint maps them. Ask the user about
a genuinely ambiguous term one at a time, recommendation first: prefer
request_user_input; in an already active user chat with no picker, ask
the one question in free text. Never use this fallback in background, CI,
autopilot, or subagent execution. Do not ask about terms the evidence
settles.
Write the document only after the user confirms the proposal. Keep the
format exactly:
# Ubiquitous Language
| Term | Meaning here | Identifiers |
|---|---|---|
| Invoice | A billable statement issued to one customer for one period. | `Invoice`, `invoice_ledger` |
Preserve existing rows and their order on an update; append new terms;
never delete a row without saying which identifiers lose their mapping.
Lint, advisory only. Run
resolved_python <plugin-root>/scripts/ubiquitous-language-lint.py --base <base>
(default base origin/main). It prints a JSON report of declared
identifiers in the diff that map to no term. Report the summary and the
unmapped identifiers to the user; suggest a term or a rename for each. The
lint always exits 0 and never blocks a gate.
Output contract
docs/ai/specs/ubiquitous-language.md: the terms table above, committed.- A short report: terms added, changed, or kept; unmapped identifiers from
the lint with a suggestion each.
This skill does not conduct a scoping interview ($grill-me), author a PRD
($speckit-prd), or explain SDD ($speckit-coach).
1---2name: ubiquitous-language-23description: Build or refresh the repository's ubiquitous-language terms document, a committed Markdown table of domain terms (term, meaning here, identifiers) that humans and agents read before designing. Use when the user asks to define domain terms, create or update a glossary or ubiquitous language, pin what a term means in this codebase, reconcile names between the spec and the code, or invokes $ubiquitous-language. Also runs the advisory identifier lint on a diff. Not for scoping interviews, PRD authoring, or general SDD coaching.4---56# Ubiquitous Language78Write and maintain `docs/ai/specs/ubiquitous-language.md`: one table of the9domain terms this repository uses, what each means here, and the code10identifiers that carry it. Grill Me and PRD authoring read it when present, so11a term is pinned once and reused instead of re-derived in every interview. In12Codex, use `$skill-name` syntax for plugin skills.1314## Ground recommendations1516Inspect the tools and skills actually available. Follow the shared17[capability-discovery](speckit-pro/skills/speckit-autopilot/references/capability-discovery.md)18and [grounding](speckit-pro/skills/speckit-autopilot/references/grounding.md) contracts.19A term's meaning comes from the code and documents that use it; disclose20uncertainty and do not invent a definition.2122## Workflow23241. **Read what exists.** If `docs/ai/specs/ubiquitous-language.md` exists,25 read it first and treat its rows as settled unless the user reopens one.26 Read `.specify/memory/constitution.md`, the technical roadmaps under27 `docs/ai/specs/`, and any PRD under `docs/` for terms already in use.282. **Scan the repository.** Collect candidate terms from module and package29 names, exported classes and functions, database tables and columns, API30 routes, and README or docs headings. Group names that split the same31 concept (`Invoice`, `bill`, `statement`) and names that overload one word32 for two concepts.333. **Propose the table.** For each term, write one row: the term, its meaning34 in this repository in one sentence, and the identifiers that carry it.35 Where the codebase disagrees with itself, propose one term and list the36 other spellings under Identifiers so the lint maps them. Ask the user about37 a genuinely ambiguous term one at a time, recommendation first: prefer38 `request_user_input`; in an already active user chat with no picker, ask39 the one question in free text. Never use this fallback in background, CI,40 autopilot, or subagent execution. Do not ask about terms the evidence41 settles.424. **Write the document** only after the user confirms the proposal. Keep the43 format exactly:4445 ```markdown46 # Ubiquitous Language4748 | Term | Meaning here | Identifiers |49 |---|---|---|50 | Invoice | A billable statement issued to one customer for one period. | `Invoice`, `invoice_ledger` |51 ```5253 Preserve existing rows and their order on an update; append new terms;54 never delete a row without saying which identifiers lose their mapping.555. **Lint, advisory only.** Run56 `resolved_python <plugin-root>/scripts/ubiquitous-language-lint.py --base <base>`57 (default base `origin/main`). It prints a JSON report of declared58 identifiers in the diff that map to no term. Report the summary and the59 unmapped identifiers to the user; suggest a term or a rename for each. The60 lint always exits 0 and never blocks a gate.6162## Output contract6364- `docs/ai/specs/ubiquitous-language.md`: the terms table above, committed.65- A short report: terms added, changed, or kept; unmapped identifiers from66 the lint with a suggestion each.6768This skill does not conduct a scoping interview (`$grill-me`), author a PRD69(`$speckit-prd`), or explain SDD (`$speckit-coach`).
racecraft-lab