Review Changes

Review a change like the senior developer who will be paged when it breaks.

The approval standard: Approve a change when it definitely improves overall code health, even if it isn't perfect. Don't block a change because it isn't exactly how you would have written it.

Reviewer

Use a reviewer when this session wrote the change, and in every round of Loop. Start one new subagent with fresh context, through the environment's orchestrator when it has one, else the harness's own subagents:

• T3 Code: delegate_task, role review.
• Codex: spawn_agent with fork_turns: "none".

Use the model the user names; if no route runs it, report the blocker. Unnamed: another vendor's model, else another model, else the session's.

State intent and out-of-scope in 1-2 sentences, run covering checks, and note missing or failing ones in the brief (the reviewer gets no history):

Review only. Do not edit, commit, push, comment on PRs, or start subagents. Run only read-only git and gh commands.
Repo: <abs path> Base: <sha> Intent: <intent> Out of scope: <scope> Checks: <results>
See: git diff <base> [-- <paths>]; git status --short (read untracked).
Follow the review-changes skill's Workflow through validation.
Reply:
VERDICT: APPROVE or CHANGES
S1 [Must fix|Should fix|Nice to have] <file>:<line> <claim>. Fix: <suggestion> (stable ids)

Do not edit scoped files while the review runs. Wait for the notice; do not poll or start a second reviewer. Timeout, error, or no reply is not approval. Check each finding yourself, then report.

Any other change, review in this session. A reviewer never starts a reviewer.

Workflow

1. Determine the review scope from the user request, PR, current branch, or relevant changed files. See Scope.
2. Gather the diff and any file/context excerpts needed to evaluate the change without guessing, plus the original requirements and the project instructions.
3. Review the change, following each reference file in turn:
   • references/bugs.md: bugs, breakages, security, devex regressions, feature-flag leaks, and other branch-audit risks.
   • references/instructions.md: compliance with the project's AGENTS.md and CLAUDE.md, code-quality rules included.
4. Record findings with file references and evidence, grouped as Must fix, Should fix or Nice to have as defined under Report. Zero findings is an acceptable outcome.
5. Deduplicate the findings. When several findings are one class of bug, report it once and list every location, so the fix covers all of them.
6. Validate every finding.
7. Report.

The review changes no code and runs only read-only git and gh commands, except Post to GitHub when the user asks for it. Loop is the one mode that edits.

Scope

Review what the user names: uncommitted or staged changes, a branch, a PR link, or files. Nothing named: the uncommitted changes, or the last commit if there are none.

• Staged: git diff --cached
• Uncommitted: git diff HEAD, plus the untracked files from git status --short
• A commit: git show <sha>
• A branch, or a diff against a base: git diff <base>...HEAD (three-dot, so the comparison is against the merge-base)
• A PR: gh pr diff <number>, with gh pr view <number> for the description

Read the surrounding code at the revision under review. When that revision is checked out, read the files on disk. Otherwise stay on the current branch and read from the revision: git show <ref>:<path> and git grep <pattern> <ref>, after git fetch origin pull/<number>/head for a PR.

Confirm the diff is non-empty before reviewing.

Validate

Treat each finding as a hypothesis to confirm or refute, not an instruction to modify code.

• Every finding needs a concrete case: "this input or situation leads to this wrong result". No case, no finding.
• For a structure finding, the concrete case is the exact code and the named restructuring that removes it.
• Re-read the lines and confirm: the caller exists, the value can really be empty, the code really is unused.
• Quote the specific code line: file:line and verbatim text. For a missing field, quote its class definition; for a nullable value, its initialization; for a race, both sides.
• For framework-generated symbols, read and quote their generating metaclass, descriptor, ORM Meta block, migration, decorator or schema. Missing literal names in the class body or grep results do not prove absence.
• If you cannot quote the motivating line(s), the finding is unverified.
• Propose the smallest fix that works. Prefer fixes that delete code. Never add layers, frameworks or config the problem does not need.
• No style taste, no "consider", no vague worries.

Validation is done when every finding is confirmed, refuted and dropped, or named under Not checked.

Report

Very simple language: short sentences, everyday words. Explain a technical term the first time you use it. The reader may never have seen this code.

Start with What this change does: in two or three sentences.

Then the findings in three groups, skip empty groups:

• Must fix: bug, security, data loss, breaks at the expected load.
• Should fix: risky code without a test, real slowness, duplication, a function that mixes jobs, code that should not exist.
• Nice to have: small speed-ups, shorter forms.

Number findings across all groups, so the user can say "fix 2 and 5". Every finding has all four parts, each one or two short sentences:

2. Orders land on the wrong day (billing/close_day.py:L40-52)
   • What this is: At midnight this job closes the day and bills all orders of that day.
   • Problem: It takes "today" from the server clock, which runs in UTC. An order placed at 00:30 in Berlin is billed on the day before.
   • Fix: Compute the day once in the shop's time zone: datetime.now(ZoneInfo("Europe/Berlin")).date(). One line, nothing else changes.
   • If we skip it: Late orders show the wrong date, and accounting fixes them by hand.

End with:

• Verdict: Ship. or Verdict: fix 1 and 3 first.
• Not checked: one line, if something mattered and you could not check it.

Nothing found: What this change does:, then Looks good. Ship. and one line on what you checked.

Lead with what matters. Order findings by leverage: correctness and security first, then structural regressions and missed simplifications, then everything else. Don't bury a real issue under cosmetic nits — a few high-conviction comments beat a long list.

• Don't soften real issues. "This might be a minor concern" when it's a bug that will hit production is dishonest.
• Quantify problems when possible. "This N+1 query will add ~50ms per item in the list" is better than "this could be slow."
• Accept override gracefully. If the author has full context and disagrees, defer to their judgment.

Post to GitHub

Only when the user asks to post the review on the PR, and from the session, not the reviewer. After validation, post one review with a comment on the line of each finding:

gh api repos/<owner>/<repo>/pulls/<number>/reviews --input - <<'JSON'
<the review>
JSON

The review is JSON with commit_id (the PR's head SHA), event set to COMMENT, body, and comments, each with path, line, side set to RIGHT, and body. A line must be in the PR's diff, or GitHub rejects the whole review, so a finding outside the diff goes in the top-level body. A comment across several lines adds start_line and start_side.

• For small, self-contained fixes, include a committable suggestion block (a fenced suggestion block that replaces the commented lines).
• Never post a committable suggestion UNLESS committing the suggestion fixes the issue entirely.
• Only post ONE comment per unique issue.

Loop

Runs when the user passes loop with the request: follow references/loop.md. Without it, the review is a single pass.