clarify
Use to run an ambiguity sweep over a written spec.md and close every under-specified point before planning or design proceeds — so two engineers can't reasonably build different things from the same spec. Triggers on "clarify {slug}", "find ambiguities in {slug}", "is the spec ready", "sharpen the spec", "/sdd:clarify {slug}", "прояснити специфікацію", "знайди неоднозначності {slug}", "чи готова специфікація". Re-reads the spec, dispatches a clean-context devil's-advocate subagent to list where the spec forks, then for each ambiguity runs AskUserQuestion to RESOLVE it (tighten §1/§5/§6 in place) or DEFER it (→ §8 Open questions with owner+due). Output: an updated docs/features/{slug}/spec.md with every ambiguity resolved or deferred — none dangling. Hard-refuse if spec.md is missing.
genkovich · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add genkovich/sdd --skill clarify技能说明
name: clarify model: inherit effort: high agents: [devils-advocate] description: > Use to run an ambiguity sweep over a written spec.md and close every under-specified point before planning or design proceeds — so two engineers can't reasonably build different things from the same spec. Triggers on "clarify {slug}", "find ambiguities in {slug}", "is the spec ready", "sharpen the spec", "/sdd:clarify {slug}", "прояснити специфікацію", "знайди неоднозначності {slug}", "чи готова специфікація". Re-reads the spec, dispatches a clean-context devil's-advocate subagent to list where the spec forks, then for each ambiguity runs AskUserQuestion to RESOLVE it (tighten §1/§5/§6 in place) or DEFER it (→ §8 Open questions with owner+due). Output: an updated docs/features/{slug}/spec.md with every ambiguity resolved or deferred — none dangling. Hard-refuse if spec.md is missing.
Skill: clarify
Ambiguity sweep over a written spec.md. It hunts the spec for under-specified points — vague terms, unmeasured NFRs, AC missing error/authz/edge behavior, unstated assumptions, conflicting requirements, undefined domain terms, missing actors, scope creep — then dispatches a clean-context devil's-advocate subagent that re-reads the spec fresh and answers one question: where would two engineers reasonably build different things from this? Each ambiguity it surfaces is closed with the user: either resolved (the spec is tightened in place) or deferred (a §8 Open-Questions row with owner + due). It exists so glossary / design never proceed on an ambiguous spec.
This is a sweep, not a full authoring stage — it does not run the shared Socratic loop or the coherence critic. Its shared dependencies:
→ ../_shared/critic.md (clean-context dispatch discipline only — the subagent here hunts AMBIGUITY, not coherence drift) · ../_shared/ask-style.md (resolve/defer question phrasing).
Depth governs how aggressively the sweep hunts + the per-finding question volume → ../_shared/interview-depth.md. (Every surfaced ambiguity is still Resolved or Deferred at every level — that's a floor, not a dial.)
Spec tightenings follow artifact_language — but the existing spec's language wins over the setting (never retro-translate mid-sweep); headings and machine tokens stay English → ../_shared/artifact-language.md.
Owner
PM + Tech Lead (the spec's co-authors resolve their own ambiguities). PM owns vague-term / scope / missing-actor calls; Tech Lead owns unmeasured-NFR / under-specified-AC / conflicting-requirement calls.
Inputs
<slug>— same feature slug used byspecify.- Gate (hard-refuse if missing):
docs/features/<slug>/spec.md. Absent → STOP and point: «runspecify <slug>first — clarify sharpens an existing spec, it does not write one». - (Optional)
CONTEXT.md— two-level: read both repo-root (project-wide) anddocs/features/<slug>/CONTEXT.md(feature-scoped; wins on conflict) →../glossary/SKILL.md; if present,## Glossaryis canonical; an "undefined-term" finding for a word already glossed at either level is a false positive (drop it). - Fast lane (XS/S): when
specifyproduced zero §8 open questions and flagged no ambiguous AC, the skip of this stage is offered byspecify's handoff (→ the fast lane in../_shared/size-matrix.md) — the user takes it there; clarify itself never auto-skips.
Protocol
- Gate + set interview depth.
test -f docs/features/<slug>/spec.md→ missing = refuse with the pointer above. Read the spec (and## Glossaryfrom both rootCONTEXT.mdanddocs/features/<slug>/CONTEXT.mdif present — per-feature wins — to suppress false "undefined-term" hits). Then set the interview depth (the opening question): readinterview_depthfrom.claude/sdd.local.mdif present (else default medium), and — unless a--depth=easy|medium|hardarg was passed — ask ONE depth-selectionAskUserQuestionphrased per../_shared/ask-style.md, with the saved/medium value as the «(Recommended)» first option. The level tunes how adversarially the sweep + subagent hunt (easy: only build-divergence that changes behavior, with assumptions stated; medium: balanced; hard: adversarial, every fork surfaced) and the per-finding question volume →../_shared/interview-depth.md. - First-pass self-sweep. Walk the spec against the eight ambiguity classes in
./references/ambiguity-checks.md(vague-term / unmeasured-NFR / under-specified-AC / unstated-assumption / conflicting-requirement / undefined-term / missing-actor / scope-creep). Note candidate findings with a§refeach — do not edit yet. - Devil's-advocate subagent (the core mechanic). Dispatch the
devils-advocateagent —subagent_type: "sdd:devils-advocate"(model perjudgment_model, roster defaultopus; efforthigh; clean context — it never saw this conversation). Pass only the slug + the spec path; it Readsspec.md(andCONTEXT.md) itself — inline nothing — and returns "two engineers would diverge here" findings. The dispatch follows the contract in../_shared/agent-roster.md(clean-isolated context, cited findings,NO_AMBIGUITIESif none). Ifdevils-advocateis unavailable at runtime, fall back to ageneral-purposeAgent with the prompt body in./references/ambiguity-checks.md. - Merge + dedupe. Union the self-sweep (step 2) with the subagent findings (step 3); collapse duplicates (same
§ref+ same class). Keep the highest-impact first (conflicting-requirement > under-specified-AC > unmeasured-NFR > undefined-term > missing-actor > scope-