/sw-review

description: Adversarial review of an increment before it ships, by a fresh context or another model family; every finding cites path:line and is re-verified. Use for "review", "qa", "critique this".
argument-hint: "[increment-id] [--full]"
metadata:
  version: "3.1.1"

sw-review: adversarial review with citations

A fresh reader hunts for real failures in the increment's diff, cites `path:line` for each, re-checks every claim, and writes `.specweave/increments/<id>/reports/review.md`. This is also the quality check: its verdict says whether the increment is ready.

Non-negotiables

• **Fresh context.** The session that wrote the code never approves it. Use a new

session, a subagent if your tool supports them, or another model (below). If you wrote this code here and cannot get a fresh context, say so in the report.

• **Every finding cites `path:line`** and a concrete failure: input or state leads to

wrong output, a crash, a hang, data loss or a leak. "Consider refactoring" is not one.

• **Re-verify.** Re-open the lines and, where a test can show it, run one. Drop what

does not survive; mark what you could not prove as `plausible`.

• **Severity** is critical, high, medium or low. Critical and high block the close.
• **At most 5 nits**, in one line at the end.

Steps

1. **Evidence first.** `specweave verify` (or its existing `reports/verify.md`): red tests, lint or build are findings before any reading. 2. **Scope.** Read spec.md (ACs, Approach, the tasks' `Files`) and review that diff, not the repository: `git diff $(git merge-base HEAD origin/HEAD)...HEAD -- <Files>`. 3. **Pass**, in this order: correctness (logic, error paths, races, off-by-one) → security (injection, path traversal, secrets, unsafe exec) → spec compliance (ACs claimed but not implemented, tests that assert nothing, mock the subject or only restate the implementation) → portability (bash-only commands, `\` paths, BOMs, `>>` in PowerShell). `--full`: run the three lenses correctness, security and spec compliance separately (in parallel if your tool has subagents). Each lens returns only a JSON list of `{"severity","file","line","summary","verified"}`; merge by deduping on (file,line), then re-open every line yourself before it goes in the report. 4. **Report** in the shape below; `specweave complete` reads its verdict line. Optional machine form, `reports/review.json`, nothing gates on it: `{"ok":false,"findings":[{"severity":"high","file":"src/a.ts","line":88,"summary":"...","verified":true}]}`. 5. **Hand back.** Each critical or high finding becomes a task in spec.md (`### T-09 Fix empty evidence` + `- AC: AC-02 | Files: ... | Test: ...`) for sw-do, or is fixed and re-tested now. Then verify again and close with sw-done.

Another model

A model reviewing code its own family wrote shares that code's blind spots. `specweave review` hands the increment to a reviewer from another family: it reads who finished the tasks from the ledger (`claude@mbp` is Claude), runs Codex with GPT-6.1-Sol on Claude-written code (Claude Opus on OpenAI-written code), and writes `reports/review-codex.md` in the shape below plus a ledger note. Exit 0: ship; 3: fix first, or no verdict; 1: no reviewer installed, or it failed.

• Run it when the review policy asks for it (below), when `review.crossModel` is true

in `.specweave/config.json`, when the user asks for another model, or when you wrote the code and have no fresh context.

• `--brief` prints the brief (ACs, tasks and their Files, the diff) to paste into any

model by hand; `--reviewer claude`, `--base origin/main` and `--timeout 45` override.

• `review.reviewer` pins one reviewer; `review.reviewers.<name>.command` adds a CLI that

reads the brief on stdin and answers on stdout, or into `{out}` when it names one.

Its findings get the same treatment as yours: re-open each line before acting on it.

Review policy

spec.md may say who reviews it, how deep, and whether closure waits:

## Review
- Reviewer: openai (gpt-6.1-sol)   # or cross-family, claude, google, xai, meta, a model id
- Depth: deep                      # or standard
- Required: yes                    # specweave complete refuses until a matching ship review

`review.policy` in `.specweave/config.json` sets the project default; the spec wins field by field. `specweave review` follows it (a deep policy runs Codex at `xhigh`). With `Required: yes`, closure accepts only a `ship` review by that family, recorded after verification, whose commit has the same content as the code being closed in each repository the tasks touch. A same-family review never satisfies a cross-family policy.

**Record every review**, whoever runs it (a SpecWithCode review thread, Codex, Claude Code, a pasted brief): write the report in the shape below, then

specweave review --record reports/answer.md --model gpt-6.1-sol --head <reviewed sha>

from the repository you reviewed. `--model` is the model that wrote the review, never the author's; `--head` defaults to HEAD. It stamps reviewer, model, family, author, repository and commit into `reports/reviews/` and the ledger, and says whether the review satisfies the policy. When the policy's family has no quota anywhere you can reach, say so to the user; never substitute another family silently.

**A review thread in SpecWithCode** (one you started for another model to review a PR):

• Use one thread per pull request. Send round 2 and later to the same thread with

`studio_thread_send`, giving the new head, what changed and which findings were answered. Start a fresh thread only when the old one failed or ran out of context, and archive the old one first.

• Ask the reviewer to clone into a scratch folder on the fast work disk (in

SpecWithCode, `~/.specwithcode/<machine>/scratch/review-<repo>-pr<N>/`), not `/tmp`, and to delete the clone when the review ends.

• Once the final verdict is recorded