| name | pr-review |
| description | Comprehensive pull request review that dispatches specialized sub-reviews (code quality, tests, error handling, comments, type design, simplification) and aggregates the findings into a prioritized action plan. Use this whenever the user wants to review a PR, review their recent changes before committing, prepare to open a PR, audit test coverage, check error handling for silent failures, verify comment accuracy, evaluate new type designs, or simplify code after review — even when they just say "review my changes", "check this before I push", or "am I ready to open a PR". |
PR Review
Run a focused, multi-aspect review of pending changes and turn the results into a short action plan. Adapted from the pr-review-toolkit plugin.
Phase 1 — Scope the review
Figure out what actually changed before launching anything:
- Run
git status and git diff --name-only (plus git diff main...HEAD if on a feature branch) to list changed files.
- If the user mentioned a PR number or branch, pull it with
gh pr view <n> / gh pr diff <n>.
- Skim the diff. Classify each file by what kinds of review it needs — this drives which specialists you launch in Phase 2.
If the diff is empty, fall back to the most recently modified files the user pointed at or that you edited earlier in this conversation. Don't invent scope.
Phase 2 — Pick the right specialists
Six specialist reviews are available. Match them to the diff — don't run all six reflexively. Each one is a subagent; invoke via the Agent tool with the subagent_type shown.
| Aspect | When it applies | subagent_type |
|---|
| General code quality, bugs, convention violations | Any code change | pr-review-toolkit:code-reviewer |
| Test coverage gaps, weak assertions, missing edge cases | Added/changed behavior, new tests, or suspiciously no tests | pr-review-toolkit:pr-test-analyzer |
| Silent failures, swallowed errors, bad fallbacks | try/catch, .catch(), err != nil, fallback branches, recover/rescue | pr-review-toolkit:silent-failure-hunter |
| Comment accuracy and rot | Added or modified comments/docstrings | pr-review-toolkit:comment-analyzer |
| Type design (encapsulation, invariants) | New or reworked types, schemas, interfaces, data models | pr-review-toolkit:type-design-analyzer |
| Simplification after review passes | Code works but feels dense; use last, not first | pr-review-toolkit:code-simplifier |
Rules of thumb:
- Always include
code-reviewer unless the user scoped you to something narrower.
- Include
silent-failure-hunter whenever error-handling code moved, even slightly — this is the highest-leverage catch.
- Skip
type-design-analyzer on pure refactors where no types changed; it produces noise.
- Hold
code-simplifier back until the other reviews have been addressed. Simplifying code that has latent bugs bakes the bugs in.
If the user passed an explicit list ("just tests and errors"), honor that and skip the rest.
Phase 3 — Launch reviews in parallel
Dispatch the chosen specialists in a single message with multiple Agent tool calls so they run concurrently. Brief each one with:
- The exact files or diff range to review (not "the whole repo").
- Any relevant project context — CLAUDE.md conventions, the PR's stated goal, language/framework.
- What form the reply should take: prioritized findings with
file:line references, and nothing else.
Each specialist already knows how to do its job — don't re-describe the methodology to it. Just hand over scope + context.
Phase 4 — Aggregate into an action plan
Wait for every specialist to return. Then consolidate — don't just stack their reports. Users drown in six independent reports; they act on one prioritized list.
Produce this structure:
# PR Review Summary
## Critical (must fix before merge)
- [specialist] Short issue — `path/to/file.ts:42`
Why it matters in one line.
## Important (should fix)
- [specialist] …
## Suggestions (nice to have)
- [specialist] …
## Strengths
- Brief, honest. Skip if there's nothing genuine to say.
## Recommended next step
One concrete action — usually "fix the critical items, then re-run `silent-failure-hunter` on the changed files."
Deduplicate findings that multiple specialists raised — attribute once, don't repeat. Drop low-confidence nitpicks; a long list of minor style points buries the signal.
Phase 5 — Offer to fix or iterate
After presenting the summary, ask the user what they want to do: fix the critical items now, re-run a specific specialist after fixes, or just note the findings and move on. Don't start editing unprompted — PR review is advisory by default.
Common invocation patterns
- "Review my changes" → Phase 1 from
git diff, pick specialists from what's in the diff, run in parallel, summarize.
- "Am I ready to open a PR?" → Full review including
pr-test-analyzer and comment-analyzer. End with an explicit ready/not-ready call.
- "Check for silent failures in the new API client" → Scope narrowly; run only
silent-failure-hunter.
- "Simplify this after the review passes" → Only
code-simplifier. Confirm other reviews are green first; if not, warn and ask before proceeding.
Why this shape
The point of splitting the review into specialists is that each one has a narrow lens and catches things a generalist sweep misses — a single "review this PR" prompt reliably under-weights test coverage, silently-swallowed errors, and type design. Running them in parallel keeps wall-clock time low; aggregating keeps cognitive load low for the user. Holding code-simplifier until the end prevents the common failure mode where cosmetic cleanups mask real bugs.
