/glossary

name: glossary
model: haiku
effort: low
agents: []
description: >
  Use to capture or update domain terms in CONTEXT.md before their meaning drifts —
  whenever a fuzzy word shows up in an interview, spec, or review and you want one
  canonical definition plus a NOT-reference so a homonym can't bite you in six months.
  Triggers on "add term {X}", "what is {X} in our domain", "add to CONTEXT", "fix the
  glossary", "define {X}", "/sdd:glossary {term}", "додай термін", "онови глосарій",
  "що означає {X}". Two-level contract: repo-root CONTEXT.md holds project-wide terms,
  docs/features/{slug}/CONTEXT.md holds feature-scoped ones; readers read both and the
  per-feature entry wins. Lazy-bootstraps the target from a template, checks BOTH levels
  for a conflicting existing entry, asks for a one-sentence definition + the concept it's
  confused with, and appends one line to ## Glossary. Skip generic tech words (HTTP, queue,
  cache) — those are not domain terms. Output: created/edited CONTEXT.md. Runs anytime, no
  input gate; specify, clarify, design and api read its ## Glossary as the canonical source
  of role and domain-term names.

Skill: glossary

Lazy utility that fixes the meaning of a domain term in `CONTEXT.md` the moment it first surfaces, so its sense doesn't drift across the pipeline. For each term it captures a one-sentence canonical definition and — when the word is ambiguous — a **NOT-reference** naming the concept it's confused with. Runs anytime, with no upstream gate: a single term mid-interview, an `undefined-term` finding `clarify` resolves mid-sweep, or a batch handed over by `specify`. The output feeds `specify` (role + domain-term names) and `design` (invariants), which treat `## Glossary` as canonical and override anything that contradicts it.

This is a capture utility, not a Socratic stage — it does **not** run the shared Socratic loop or critic. The one shared dependency is question phrasing: → [`../_shared/ask-style.md`](../_shared/ask-style.md)

Term definitions follow `artifact_language` — the `## Glossary` heading and the other H2s stay English, the frontmatter stays the **template's** (`status: Living` + `updated_at:` — never write `artifact_language` or any other settings key into the file) → [`../_shared/artifact-language.md`](../_shared/artifact-language.md).

Owner

Whoever drives the conversation — anyone who spots ambiguity. Tech Lead approves the canonical form when a term is contested.

Inputs

• `<term>` — the domain word/phrase to fix. If not given, ask for it.
• (Optional) `<slug>` — feature slug; targets `docs/features/<slug>/CONTEXT.md`. Absent → repo-root `CONTEXT.md`.
• (Optional) `pending_glossary_terms` — a batch handed over by `specify` after it writes the spec. Process each term in turn.
• (Optional) an `undefined-term` finding from `clarify` — `clarify` invokes this skill **mid-stream**, one term at a time, the moment such a finding is Resolved (it never invents a meaning inline; the canonical definition lands here).
• (Optional) proposed phrasings already surfaced in an interview/brainstorm — offer them as definition options instead of asking blank.

Protocol

1. **Pick the target (the two-level contract).** Root `CONTEXT.md` = **project-wide** terms (meaningful across features); `docs/features/<slug>/CONTEXT.md` = **feature-scoped** terms (meaningful only inside that feature). If `<slug>` is given → the per-feature file; otherwise → repo-root. A term lives in exactly **one** of the two files — never split or duplicate it across levels. Readers (`specify`, `clarify`, `design`, `api`) read **both** files; on a conflict the per-feature entry wins. 2. **Generic-term filter.** Reject words that name infrastructure or transport rather than the business domain (e.g. HTTP, queue, cache, the datastore, the broker, a framework). Refuse: «`<term>` is technical, not a domain word — its choice belongs in the SAD or an ADR, not the glossary». Continue only for genuine domain vocabulary. 3. **Bootstrap (lazy).** `test -f <target>`. Missing → copy [`./templates/CONTEXT.md`](./templates/CONTEXT.md) to `<target>`. Present → read it. 4. **Conflict check — both levels.** `grep -i "^- <term>" <target>` AND the other level's file when it exists (root `CONTEXT.md` ↔ `docs/features/<slug>/CONTEXT.md`).

• Found (either level), identical sense → STOP, report «already in the glossary» + which file holds it — never duplicate a term across levels.
• Found (either level), different sense → escalate via `AskUserQuestion` (phrasing per [`../_shared/ask-style.md`](../_shared/ask-style.md)): «`<term>` is already defined as `<existing>` in `<file>` — same concept or a different one?». If different: a genuinely feature-scoped narrowing goes to the per-feature file (readers let it win there); otherwise propose a disambiguating pair of names (e.g. a billing-scoped vs a runtime-scoped variant) and fix both.
• Not found in either → continue.

5. **Ask the canonical definition** — one `AskUserQuestion`: «Define `<term>` in this domain, in one sentence». Offer interview/brainstorm phrasings as options when available; otherwise free text. 6. **Ask the NOT-reference** — one `AskUserQuestion`: «Which concept does `<term>` get confused with, so a future reader doesn't mix them up?». No plausible homonym → `None`. 7. **Compose one line.** `- <term> — <one-sentence definition>. NOT <confused concept + how it differs>.` — or, when step 6 = None, `- <term> — <definition>.` 8. **Append under `## Glossary`.** Read the file, insert the line in `## Glossary` (alphabetical if the section is already sorted, else at the end). Never rewrite existing entries. 9. **Prune empty H2s.** On a fresh bootstrap, delete `## Invariants` / `## Out of scope` if they hold no real content — only `## Glossary` is mandatory. (A genuine invariant or out-of-scope note goes in its section, never as implementation detail.) 10. **Structural self-check** — per [`../_shared/self-check.md`]