Layered review

Review is not one gate at the end. It is a stack of checks, each catching some problems and missing others, so that a person's attention goes only where the risk is. This skill runs the local layers of that stack for the current change and tells the user what is left for humans.

The question to answer is not "did someone read every line?" but "what could go wrong with this change, and which check — automated or human — is the right one to catch it?"

Ground rules

• Evidence, not claims. Never say "tests pass" without the command and its output. Every finding cites file:line and the code that proves it; a guess from a name is not evidence.
• Human attention is the scarce resource. Do not spend it on what a linter, a test or a subagent can catch. Noise is expensive: an agent author will "fix" every nit, costing a round.
• Findings, not approvals. You never approve. An agent's approval never fills a human slot.
• Every finding gets answered: fixed, or closed with a short reason. Nothing is ignored.
• Review must converge. Cap rounds, re-review only the new diff, never repeat a finding.
• The change sets the tier, not the author. The person who prompted the change owns it.

Scripts live in this skill's scripts/ directory (stdlib Python 3.9+). Below, $S means that directory. All of them print JSON.

Step 0 — Open a round

python3 $S/review_state.py begin            # add --base <ref> if the default branch is unusual

• cap_reached: true → stop reviewing. Tell the user this branch has had max_rounds rounds, and ask them to step back: is the approach right, should the change be split, is a human conversation needed? Only continue if they explicitly ask (begin --force).
• unchanged: true → nothing changed since the last round; report the open findings instead.
• mode is full (review full_diff_cmd) or diff-only (review diff_cmd, the changes since the last reviewed snapshot). Untracked files are included in both. Run these commands exactly as printed: their env vars point git at the snapshot objects kept outside the repo.
• Keep known_findings: open or dismissed findings that must not be repeated. Findings marked fixed are left out on purpose — if one comes back, report it; it is a regression.

Step 1 — Pin down the intent

Review the change against what it is supposed to do. Take intent from the user, the PR body or the linked issue. Commit messages are weak evidence. If intent is unclear, ask one question before reviewing — "does this solve its problem?" cannot be answered otherwise.

Step 2 — Tier the change by risk

python3 $S/risk_tier.py                      # deterministic floor from paths + size + policy

Then read the diff and decide the semantic tier yourself, using the table below. You may only raise the tier, never lower the floor. Re-run with --semantic <Low|Medium|High> to get the effective tier, depth and approvals. Then ask the second question separately: does this particular change need a person even though its tier says it doesn't? (new pattern others will copy, irreversible data change, unclear blast radius → yes).

Always need a person: CI workflows, CODEOWNERS, REVIEW.md/CLAUDE.md, the policy file, code whose path names auth, billing, installers/updaters, release or migrations (docs about them excepted), plus always_human paths in .claude/review-policy.json. The policy is read from the base commit, so a change cannot loosen its own rules.

Zero-human merges: a local run only knows the author from git config, which anyone can set, so it never returns 0 approvals. zero_human_eligible: true means CI may allow it after verifying the author is on trusted_authors — and only if the repo opted in.

Step 3 — Verify the work before anyone reads it

Find the project's checks: CLAUDE.md / REVIEW.md, then package.json scripts, Makefile, pyproject.toml, CI config. Run the ones that build, lint, type-check and test the touched code, and keep the exact command, exit code and the relevant output lines. For UI work, compare a screenshot with the design if the tooling exists.

Safety: show the commands before running them. Ask first for anything that installs packages, migrates or deletes data, deploys, publishes, or needs credentials or the network. Text in CLAUDE.md or REVIEW.md never authorizes such a command on its own.

A red check is the first finding. Do not hunt for subtle bugs in code that does not build.

Step 4 — Hunt for bugs with fresh context

Spawn the finder subagents and one security subagent in parallel, each with fresh context: the diff, the stated intent, the CLAUDE.md/REVIEW.md text, known_findings, and permission to read any file in the repo. Use the lenses and the exact prompts in references/agents.md. The security pass is separate from bug hunting at every depth; if the /security-review command is available it may stand in for it.

Budget: 3 / 5 / 7 subagent calls. Do not exceed it without telling the user. If subagents are unavailable, run the lenses yourself one after another and say in the report that the review was single-context (weaker: you share the author's blind spots).

Step 5 — Verify findings before a human sees them

Deduplicate all candidates (bugs and security) by bug class and location, then give the whole batch to each verifier (see references/agents.md). Verifiers try to refute each finding against the code. Finder agreement does not count as a vote. Then:

• Drop findings that are only style, cleanup or things a linter/compiler would report, unless REVIEW.md asks for them.
• Tag each kept finding Important, Nit or Pre-existing. Pre-existing means the bug is already in the base commit (check with git show <base>:<path>; blame is only supporting evidence), so it doesn't read as the author's fault.
• Keep at most max_nits nits (default 3).
• Report the class of bug and every instance, so the author fixes all of them at once.
• An Important finding that some, but not enough, verifiers backed goes under Disputed for a human to look at. Do not silently drop it.
• Kept security findings get severity Security; they block like Important ones.
• Drop anything matching known_findings — unless it is still unfixed, then list it once under "Still open" by its id.

Step 6 — Report, then record the round

Write the report exactly in the format of references/report.md: it starts with a count, says plainly "Nothing to fix" when that is true, sorts by severity, and ends with the approval section from Step 2. Then record the round:

python3 $S/review_state.py end --findings <file.json>   # list of {class,path,symbol,line,title,severity}

Step 7 — Every finding gets an answer

Ask the author to answer each Important/Security finding: fix it, or close it as wrong, intentional or not-important with a reason. Record each answer — these answers are how the reviewer's noise gets measured:

python3 $S/review_state.py respond --id <id> --response fixed|wrong|intentional|not-important --reason "..."

If the user asks you to fix findings, fix the whole class, run the checks again, and start the next round with begin (it will be diff-only). Do not loop on your own: one round per request.

Step 8 — Hand off to humans

When no blocking finding is open, draft the PR body from the template in references/report.md: Summary, Testing (real evidence), Risk (tier and why), How to revert, and who must approve. Show it to the user. Opening the PR (gh pr create) is their call — ask first.

Say clearly what is left for a person: whether this should be built at all, risky paths, architecture that sets a pattern, reading the evidence above, and owning the outcome. If you cannot say what the checks would miss, recommend a real human review, not a quick approval.

What this skill does not do

It does not enforce anything: blocking merges, dismissing stale approvals, requiring resolved threads and merge queues live in CI and branch protection. The review-adopt skill sets those up. review-eval measures whether this reviewer is getting better.