SDD Review
The Review phase of SDD: the only verification gate. It judges the implemented work against the
acceptance criteria and the project's rules, writes review.md with a READY / NOT READY verdict,
and — on READY — commits what is left and opens the PR. It never implements anything.
The feature diff
Compute it as in feature-diff.md: the commits
/sdd:implement made per task, uncommitted changes and untracked files against the merge base, generated globs excluded, one diff
per sibling repository on the feature branch. Every step and every agent uses that definition.
Steps
1. Pre-flight and configuration
- Branch ≠ default branch. The feature is the
specs/*/spec.mdwhose**Branch:**equals the current branch (specs/<current>/); every task in itstasks.mdisreviewordone. - Read
projects,reviewandactionsfromspecs/capabilities.yml(keys and defaults: capabilities.md; an unknown key such as the oldui:is ignored). Only the oldspecs/capabilities.mdexists → STOP: "Run/sdd:doctor initto migrate it."
2. Verify — in parallel
Start everything that does not depend on another result in one message and wait for all of it:
- Tests (
tests: run): for each project the diff touches, itscoveragecommand fromspecs/constitution.md§2 (elsetest); independent projects together. Keep the result per project — counts, coverage, failing test names.tests: skip→ "skipped". spec-verifier(Agent tool): the feature folder, the diff definition, the generated globs. Returns the JSON with AC status, non-goal violations, out-of-scope, drift and per-task status.- Extra checks and audit agents from
reviewthat areagent:<name>—review.checksentries (e.g. a QA agent that runs the app and tests the functionality against the acceptance criteria) andagent:audit values (review.default,review.projects) for the touched projects. Brief each with the spec's AC, the touched projects, how to start the app (devin constitution §2) and the diff definition. A check returnsPASS | FAIL | SKIPPEDwith findings.skill:entries are not run here: pass them to the reviewer.
3. Reviewer
Invoke reviewer (Agent tool) once with: the feature folder and review.md path, the diff definition
and changed files per project (kind, stack), every result from step 2, and the skill audits to run
(skill: values from review, or auto), and the ## Accepted list of the previous review.md
if there is one. It checks the constitution's rules, runs the skill audits, writes review.md and
returns {verdict, blockers, warnings}; each blocker says whether the user may accept it.
Accepting blockers. NOT_READY and every blocker acceptable (an out-of-scope change, a
constitution rule, a non-critical audit finding) → ask once with
AskUserQuestion, listing them: "Fix them" (Recommended) / "Accept all and continue". Accepted →
add each with the user's reason under ## Accepted in review.md, set its verdict to READY and go
on as READY. Failing tests, unmet AC, non-goal violations, failed checks and critical
security/accessibility findings are never acceptable.
4. Record the outcome
From the spec-verifier result, whatever the verdict:
spec.md: tick- [x]the met acceptance criteria and untick the unmet ones.tasks.md: a task with unmet AC goes back toin-progress; complete tasks stayreview.
5. READY → publish
Set the complete tasks to done and **Status:** in spec.md and plan.md to done (so the
commit carries it; see status-lifecycle.md). Then, per publish::
off→ stop; report the verdict andreview.md.ask(default) → show the commit title (when something is left to commit), the PR title and the exact list of files you will stage (what is still uncommitted:specs/<slug>/with the statuses,review.md, and any task files/sdd:implementdid not commit), viaAskUserQuestion("Commit and open PR" (Recommended), "Commit only", "Stop here"). Never stage anything else — nevergit add -A(it sweeps in untracked files such as.env*).
Commit what is left with actions.commit and open the PR with actions.pr
(skill: / agent: / command:). Unset → do it yourself: git add -- <confirmed files>, a
Conventional Commits message (<type>(<slug>): <Summary of spec.md>, trailer Epic: <EPIC>; nothing
left → no commit), gh pr create with a body
holding the summary, the changes from plan.md, the test results and a link to spec.md.
Several repositories: confirm once for all, then publish per touched repo as in sibling-repos.md.
6. NOT READY
Do not commit or open a PR. List the blockers and, for each unmet acceptance criterion, the task to re-run
(/sdd:implement T3). Report briefly: verdict, blockers, review.md path.
Constraints
- Never commit the review outcome or open a PR on NOT READY, or without the user's confirmation when
publish: ask. Fixes after NOT READY are new commits with the sameTask:trailer. - Never
git add -A/git add .: stage the confirmed list only. - Run each check once; do not loop them. Verification agents never flag the generated globs.