sdd-implement-spec

/sdd-implement-spec — implement a feature spec

You are operating within a Spec-Driven Development (SDD) workflow. See .claude/rules/sdd-constitution.md.

This skill takes one unprocessed feature spec (a specs/YYYY-MM-DD-<slug>/ directory whose ## Phase N — ... heading in specs/roadmap.md does not yet carry the ✅ lifecycle marker) and drives the work end-to-end: cuts the feature branch, walks plan.md task groups, runs the verification gates, commits atomically per group, runs a pre-push review (built-in /review plus three parallel deep-review subagents), pushes, opens a PR, and reports back on implementation, review, and verification.

The skill drives implementation — it is not merely scaffolding around it. The actual code changes happen in the main loop guided by plan.md. The spec itself is read-only.

Inputs

Argument in $ARGUMENTS (optional):

• empty → enumerate unprocessed specs and pick via AskUserQuestion
• integer (24, 25) → spec whose requirements.md H1 starts with # Phase <N>
• slug fragment ("gate-allowlist") → case-insensitive contains match against spec dir slugs (the portion after the date prefix); if ambiguous, list matches and ask
• relative path (specs/2026-05-21-gate-allowlist) → use directly; verify it exists and is a valid spec dir

Hard constraints

• The spec is read-only during implementation. Do not edit specs/<dir>/requirements.md, plan.md, or validation.md. If the spec is wrong, incomplete, or contradicts current code, stop and surface the gap; the user owns spec edits and may re-run the skill after revising.
• plan.md is the source of truth for ordering and scope. Walk groups sequentially. Each non-Verify group produces one primary atomic commit; verification (Phase 7) may add small fix-up commits if a check fails. Tasks within a group can interleave as needed for the change to make sense.
• validation.md is the source of truth for done. Every numbered check must pass before opening the PR. If a check fails and cannot be fixed without changing the spec, stop and surface it.
• Roadmap completion marking is part of plan.md. The convention is for plan.md to include "Append ✅ to the ## Phase N — <Title> heading in specs/roadmap.md" as a numbered task in its final docs/lifecycle group; respect it. If plan.md does not include the completion-marking task, surface the gap before starting — do not improvise it.
• Conventional Commits + DCO sign-off. Per .claude/rules/conventional-commits.md and .claude/rules/git-workflow.md. Every commit git commit -s; header ≤ 69 chars; type+scope reflect the group's primary subject; lowercase imperative description, no trailing period.
• Atomic, surgical commits. Per .claude/rules/git-workflow.md and .claude/rules/karpathy-guidelines.md: one logical change per commit (applies equally to primary group commits and Phase 7 verification fix-ups), touch only what the change requires, do not improve adjacent code.
• No destructive git. No --force, no reset --hard, no --no-verify. If a pre-commit hook rejects the commit, no commit was created — fix the underlying issue, restage, and retry the same git commit (don't add a duplicate). The "never amend" rule applies after a commit already exists and you discover a problem; in that case add a fix-up commit on top instead of amending.
• Stage explicit paths. Never git add -A or git add . — name the files the group touched. After staging, verify git diff --cached --name-only lists only those paths.
• Ask the user when work surfaces a real decision. During Phase 6 (implementation) and Phase 7 (verification), if a task surfaces a choice the spec doesn't lock down — multiple valid approaches a reasonable engineer would weigh, an adjacent change the spec didn't anticipate, drift between spec and code that has more than one reasonable resolution, ambiguous validation expectations — use AskUserQuestion to surface it inline rather than picking silently or halting outright. Halting is for genuine blockers; questions are for genuine choices. The user is the source of truth when the spec isn't.
• Track spec deviations and draft a retrospective. Maintain a running list across Phases 6, 7, and 8 of any concrete divergence between what the spec said and what the implementation had to do. Sources of deviations: file/line targets in plan.md that drifted, scope the spec missed but the work required, validation checks that needed clarification, fix-up commits that revealed a gap. Each tracked item is one sentence naming the spec file (requirements.md / plan.md / validation.md), the section, and what changed in practice. Phase 9 emits this list in the PR body's ## Spec deviations section; Phase 8.5 commits a specs/<date>-<slug>/retrospective.draft.md on the branch so the reviewer has a structured starting point. The draft is provisional — the reviewer promotes it to retrospective.md (edit + rename) or deletes it before merge. Root cause and lessons are left as placeholders; the human fills them in. See .claude/rules/sdd-constitution.md (post-implementation feedback loop).