Peer Review Skill

A separate read-only agent reviews the diff so the author’s intent does not color the review. Use this before shipping or whenever an unbiased look at pending changes is wanted.

Workflow

1. Capture the diff

Compute the review target and keep the text: the diff against the base branch (git diff "$CLAUDE_CODE_BASE_REF"...HEAD), or uncommitted work (git diff / git diff --cached). Get its changed paths, then capture git log -n 30 --no-merges --oneline -- <changed paths> so the review can distinguish a first defect from a repeated local repair.

2. Launch the reviewer

Invoke the code-reviewer subagent (.claude/agents/code-reviewer.md) via the Agent tool, passing the diff and path history from step 1 in the prompt — the agent is read-only (Read/Grep/Glob, model: opus) with no shell, so it cannot fetch either itself. It reads the surrounding files for context on its own.

3. Triage and fix

For each finding, assess validity first — the reviewer can be wrong. Then:

• Blocker / Should-fix: fix it, re-running the project’s tests/lint as needed.
• Nit: apply if cheap; otherwise note and move on.
• Invalid: state why in one line and skip.

Do not weaken or delete tests to make a finding “go away” (see CLAUDE.md).

4. Re-review to a fixed point

After fixing, launch a fresh code-reviewer pass with the updated diff — fixes introduce their own bugs and the prior review is now stale. Stop when a full pass returns nothing actionable. The cap is at most three passes (.claude/rules/development-workflow.md § Self-critique); if findings persist there, summarize what is left in the report and proceed rather than looping silently.

5. Report

Summarize what the reviewer flagged, what you fixed, and anything deliberately deferred.

When NOT to use

• Creating a PR end-to-end — use pr-creation (it already runs its own critique loop).
• Trivial edits (typo fixes, single-line config tweaks) — say so and skip.

Examples

Example 1: Pre-PR review

User says: “Review my changes before I open the PR.”

1. Runs git diff "$CLAUDE_CODE_BASE_REF"...HEAD — 4 files changed.
2. Launches code-reviewer, passing that diff in the prompt.
3. Reviewer returns one Blocker (off-by-one in pagination) and one Should-fix (duplicated parser).
4. Fixes both, reruns pnpm test — green. Commits.
5. Re-reviews with the new diff — clean. Reports the two fixes and that the second pass found nothing.

Example 2: Reviewer disagreement

User says: “Peer review this branch.”

1. Launches code-reviewer with the branch diff; it flags a try/catch as a “swallowed error.”
2. Author checks: the catch rethrows after cleanup — the finding is invalid. States why, skips it.
3. Applies the reviewer’s other (valid) Nit, re-reviews to a clean pass, reports.