peer-review

name

peer-review

description

Runs a fresh, unbiased review of pending changes by delegating to the read-only code-reviewer subagent, then triages and fixes the findings. Activate when the user asks to "review this", "peer review", "get a second opinion", "review my changes/diff/branch", or wants a review pass before opening a PR. Distinct from the built-in /code-review and /review skills: this one drives the project's code-reviewer agent to a fixed point.

Peer Review Skill

Codifies the “fresh second-Claude reviewer, no implementation bias” pattern: 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).

2. Launch the reviewer

Invoke the code-reviewer subagent (.claude/agents/code-reviewer.md) via the Agent tool, passing the diff text from step 1 in the prompt—the agent is read-only (Read/Grep/Glob, model: opus) with no shell, so it cannot fetch the diff 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. Cap at ~5 passes; if findings persist at pass 5, summarize what is left and ask the user 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.