/sdd

name: sdd
description: Spec-Driven Development. Interview → spec with acceptance criteria → plan → test-first execution. `/sdd full` runs the 6-phase pipeline instead.
level: 3

SDD (lite)

Interview → Spec+AC → Plan → Test-first execute. Artifacts live in `spec/<slug>/` at project root (one folder per feature). No implementation code before `spec/<slug>/plan.md` is approved.

If args start with `full`: read and follow `phases/spec.md`, `phases/criteria.md`, `phases/rules.md`, `phases/review.md`, `phases/tasks.md`, `phases/execute.md` (relative to this skill's directory) in that order, confirming with the user after each artifact. Pick the slug as in Entry; every phase writes to `spec/<slug>/`. Then stop reading this file.

Entry

1. `git status --short --branch`; list `spec/*/`. 2. Pick the slug (kebab-case, max 40 chars, descriptive of the feature):

• On a feature branch, use the branch name without the prefix (`feat/csv-export` → `csv-export`) if `spec/<that>/` exists or the task matches it.
• Otherwise derive it from the task (`add CSV export of reports` → `csv-report-export`) and show it to the user in the first message so they can correct it.
• If several `spec/*/` folders exist and the task is unclear, ask which one to resume via AskUserQuestion.

3. Resume at the first missing artifact in `spec/<slug>/` and say where you resume. 4. Task text comes from args or the user's message. Ask only if there is none. 5. Skip the flow for tasks prefixed `quick:`.

1. Interview (no file yet)

• Read the code first; never ask what the code answers.
• One question at a time via AskUserQuestion: 2-4 concrete options, a recommended pick, one-line reason why it matters.
• Ask only if the answer changes behavior, scope, or a safe assumption. Otherwise decide and record it as an assumption.
• Stop when an implementer would have no questions left. Typically 3-7 questions; more means the task should be split.

2. Spec → `spec/<slug>/spec.md`

One file, short:

• Summary (2-3 sentences)
• Decisions and assumptions (bullets, with the reason)
• Out of scope
• Acceptance criteria: `AC-1`, `AC-2`, ... one observable outcome each, EARS form:

`When <trigger>, the <system> shall <response>.` / `If <bad trigger>, then the <system> shall <response>.` / `While <state>, ...`

• Bounded values: three ACs (inside, at, beyond the bound).
• Error paths: state the response and whether it is all-or-nothing.
• No implementation details, no "fast"/"correct" without a number.

Show a 5-line summary, then AskUserQuestion: continue or revise.

3. Plan → `spec/<slug>/plan.md`

• Design in under 10 lines: components, flow, new dependencies. Record only deviations from project conventions (read CLAUDE.md, build files, existing layout first) and deliberate "not using X" decisions.
• Tasks as a checklist, ordered, each under ~1 hour: `- [ ] T1: <what> (AC-1, AC-2) — verify: <test or command>`
• Group into phases (max 4); end each phase with `CHECKPOINT`.
• Every AC appears in at least one task. Self-check this; if something is unclear, go back to the interview instead of guessing.
• For large or risky features only (many ACs, migrations, new infra), add a "Risks" list of up to 5 items with mitigations.

Show the plan, AskUserQuestion: approve or revise.

4. Execute (test-first)

Per task, in order, no skipping:

1. Write tests for the task's ACs; run them; confirm they fail for the right reason (red). 2. Implement the minimum to pass (green); run the full test suite, type check, and linter. 3. If still failing after 2 different attempts, stop and report: what failed, what you tried, 2 options, your recommendation. 4. Tick the task in `plan.md` (`- [x]`). Do not edit `spec.md` during execute; if the spec is wrong, stop and say so.

At each `CHECKPOINT`: report tasks done, ACs satisfied (AC → test file), test/lint results. Then wait for the user: `ok`, `revise T<n>: ...`, or `rollback T<n>`.

At the end: AC coverage table (AC → test) and one command to run the tests.