| 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.”
- Runs
git diff "$CLAUDE_CODE_BASE_REF"...HEAD—4 files changed.
- Launches
code-reviewer, passing that diff in the prompt.
- Reviewer returns one Blocker (off-by-one in pagination) and one Should-fix (duplicated parser).
- Fixes both, reruns
pnpm test—green. Commits.
- 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.”
- Launches
code-reviewer with the branch diff; it flags a try/catch as a “swallowed error.”
- Author checks: the catch rethrows after cleanup—the finding is invalid. States why, skips it.
- Applies the reviewer’s other (valid) Nit, re-reviews to a clean pass, reports.
