sdd-clarify

/sdd:clarify — Refine a feature specification

You are refining an existing feature specification by identifying gaps and asking clarification questions. This is the refinement step after /sdd:specify. Follow these steps exactly, in order. Do NOT skip steps. Do NOT read source code — only spec.md, constitution.md, and state.json.

Coaching Layer

Clarify is one of the most important teaching moments in SDD — the user learns to think rigorously about their own spec. But without framing, it can feel like an interrogation. Claude must set the right tone.

Rules:

1. Normalize gaps — calibrated. Read completed_features. If 0, orient the user before the first question: "All first-draft specs have gaps — finding them is exactly what this step is for. I'll ask you a few questions about things that weren't clear or scenarios that weren't covered. For each one, I'll explain why it matters." If 1+, skip the normalization — the user knows the drill.
2. Name the gap type. Before each question, state the gap type (ambiguity, assumption, edge case, or structural gap). Check .sdd/state.json field milestones.gap_taxonomy_explained. If false, explain each type briefly the first time it appears and set the milestone to true after the session. On subsequent sessions, name the type without re-explaining — the user already knows the taxonomy.
3. Teach prevention, not just detection. After the user answers, add a brief pattern annotation as a coaching note. Example: "Tip: whenever your spec references external data, define where it lives and what happens when it's unavailable — this prevents guesswork during implementation."
4. Acknowledge that finding gaps is positive. The message "your spec is incomplete" can feel like failure. Reframe: finding gaps now prevents bugs later.
5. Track coaching for fade. Read .sdd/state.json field coaching_profile at the start of the session. For each gap found during analysis, increment scaffolded for the relevant category (e.g., edge_cases if you found a missing edge case, data_models if you found undefined entities). For each area where the spec was already solid and needed no clarification, increment unscaffolded for that category — but cap unscaffolded increments at one per category per session to prevent a single well-written spec from disproportionately boosting competence scores. Update coaching_profile in state.json when updating state in Step 7.