glossary
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 ## Glos
genkovich · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add genkovich/sdd --skill 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
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.
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; targetsdocs/features/<slug>/CONTEXT.md. Absent → repo-rootCONTEXT.md. - (Optional)
pending_glossary_terms— a batch handed over byspecifyafter it writes the spec. Process each term in turn. - (Optional) an
undefined-termfinding fromclarify—clarifyinvokes 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
- 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. - 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. - Bootstrap (lazy).
test -f <target>. Missing → copy./templates/CONTEXT.mdto<target>. Present → read it. - Conflict check — both levels.
grep -i "^- <term>" <target>AND the other level's file when it exists (rootCONTEXT.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): «<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.
- 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. - 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. - Compose one line.
- <term> — <one-sentence definition>. NOT <confused concept + how it differs>.— or, when step 6 = None,- <term> — <definition>. - 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. - Prune empty H2s. On a fresh bootstrap, delete
## Invariants/## Out of scopeif they hold no real content — only## Glossaryis mandatory. (A genuine invariant or out-of-scope note goes in its section, never as implementation detail.) - Structural self-check — per [
../_shared/self-check.md]