parallel-pr-review

Parallel PR Review

Overview

Review many open PRs at once by fanning out one read-only review subagent per PR (or per stack), each producing a structured verdict, then synthesizing a cross-PR summary and posting reviews. The reviewer (you) stays in the loop holding conclusions; subagents absorb the per-diff reading.

Core principle: one agent per independent unit of review, a consistent rubric and output format across all of them, then a synthesis pass that finds what no single PR review can see.

When to Use

• "Review the open PRs" / "anything new to review?" / recurring review loops
• A batch of PRs from one author, or a stacked series (PR based on another PR's branch)
• Any time reading every diff yourself would blow context

When NOT to use: a single PR (just review it directly); a PR you authored mid-task (use normal self-review).

Workflow

1. Enumerate + triage. List PRs with the metadata that drives decisions:

   gh pr list --state open --limit 100 --json number,title,author,additions,deletions,baseRefName,mergeable \
     --jq 'sort_by(.number) | reverse[] | "#\(.number) @\(.author.login) +\(.additions)/-\(.deletions) base:\(.baseRefName) \(.mergeable)  \(.title)"'
   

   • base != main ⇒ stacked PR (review with its stack, note merge order).
   • CONFLICTING ⇒ flag; have the agent diagnose cause + resolution. Re-check: some "conflicting" clears after an upstream rebase.
   • Compare against PRs already reviewed in prior passes — only review what's new (and re-check any that grew).

2. Group. One agent per PR for standalone changes; one agent per stack (review each stacked PR's own gh pr diff, in dependency order). Give security-sensitive PRs (contracts, crypto/keys, auth/attestation, money/billing, DoS bounds) their own dedicated agent with an adversarial prompt. For large or structural PRs (big refactors, new modules, files crossing ~1k lines), add a dedicated maintainability-lens agent (see Maintainability lens below).

3. Fan out review subagents in parallel — all in one message so they run concurrently. Use a code-review agent type; each gets the prompt template below. Tell them not to modify files.

4. Synthesize. Collect verdicts into one table; then write the cross-cutting section: recurring bug classes, themes spanning PRs, "already rebased/clean now," and which PRs to land first.

5. Post (only when asked) — see Posting.

6. Clean up review branches subagents fetched (see Cleanup).

Subagent prompt template

Give each agent: the PR number(s), how to get the diff (gh pr diff <n>), an instruction to read surrounding context with Read/Grep, and a fixed rubric:

Focused [adversarial, if security] code review of PR #<n> in <repo path>.
Get the diff: `gh pr diff <n>`. Read surrounding context with Read/Grep on the
actual changed files. Do NOT modify any files.

Review priorities, in order:
1. Correctness — real bugs, races, wrong-key/off-by-one, missed cases.
2. Security — <adversarial angle for this PR: spoofable identity, replay,
   unbounded growth/DoS, fail-open, key reuse, double-pay, TOCTOU>.
3. Privacy/logging — <repo's logging rule, e.g. "log ids/counts/sizes/durations/
   error-types only, never prompts/completions/keys/raw bytes">.
4. Tests — are they non-vacuous (would fail on a real regression)? CI-runnable
   (not #[ignore]/feature-gated off)? Deterministic (no port/timing flake)?
5. Structural quality (behavior-preserving) — would a cleaner reframing DELETE
   categories of complexity, not just polish? Flag: ad-hoc conditionals/special
   cases bolted onto unrelated flows; feature-specific logic leaking into a
   general module; thin wrappers adding indirection without clarity; unnecessary
   casts / `any` / optional params muddying contracts; copy-paste instead of an
   extracted helper; a bespoke helper duplicating an existing canonical utility;
   a file pushed past ~1k lines without strong reason. Propose the restructuring,
   not the incremental tidy. Must not change semantics; outranked by 1-2.
6. [stacked/conflicting] Diagnose the conflict: git fetch origin; git log
   --oneline origin/main -20; name the colliding PR and the resolution.

Output: one-line summary, VERDICT (APPROVE / APPROVE WITH NITS / REQUEST CHANGES),
then numbered findings `severity [file:line] — issue → suggested fix`.
Be precise and skeptical; distinguish real bugs from speculation.

Tailor priority 2 per PR — that targeting is what makes the reviews sharp (e.g. "is the owner-proof replayable?", "is this per-deployment map bounded + pruned on undeploy?", "does the validity check use a spoofable clock?").

Output format (consistent across all agents)

• Verdict: APPROVE / APPROVE WITH NITS / REQUEST CHANGES (add REJECT/CLOSE for superseded/duplicate PRs).
• Findings: severity [file:line] — issue → fix, severities Critical / Important / Low / Nit, plus Praise/Good for verified-correct load-bearing code.
• Demand non-vacuity checks on test PRs: a test that would pass even with the bug present is a finding, not coverage. Agents can prove it by mutation ("deleting X makes it fail").

Maintainability lens (thermo-nuclear)

Rubric priority 5 is bug-and-risk review's structural complement: it audits behavior-preserving quality. Run it on every PR; for large/structural PRs give it a dedicated agent (as security PRs get a dedicated adversarial agent).

• Bias to deletion ("code judo"). The win is a restructuring that makes whole branches / helpers / conditionals disappear — not "a bit cleaner." Reject incremental polish when dramatic simplification is available. Prefer removing pieces over redistributing complexity.
• Flag in impact order: (1) structural regressions; (2) missed dramatic simplifications; (3) spaghetti/branching growth (ad-hoc conditionals, scattered special cases); (4) boundary/type-contract problems (casts, any, optional params); (5) file-size/decomposition (a PR pushing a file past ~1k lines without strong reason); (6) modularity/abstraction (feature logic in general modules, thin wrappers, bespoke helpers duplicating canonical utilities); (7) legibility.
• Approval bar: no structural regression, no obvious missed simplification, no unjustified file growth, no new spaghetti, no hacky abstraction obscuring intent.
• Guardrails: every structural finding must be semantics-preserving and must cite the concrete restructuring; correctness and security still outrank it; don't let it become style-nitpicking (a formatter's job). Adapted from cursor-team-kit's thermo-nuclear-code-quality-review.

Posting

Post only when the user asks. Default to review comments, not formal approve/request-changes, when reviewing someone else's PRs — a comment carries the verdict in its body without flipping GitHub's merge-blocking state unilaterally.

# write each body to a file (heredocs survive markdown/newlines safely), then:
gh pr review <n> --comment --body-file /tmp/reviews/<n>.md

• Loop over PRs; print OK/FAILED per PR so a failed post is visible.
• For a superseded/duplicate PR, post a "close as superseded by #X" conversational comment (gh pr comment) instead of a review.
• Surface big cross-cutting observations as their own gh pr comment so they're actionable, not buried in a long review body.

Cleanup

Subagents fetch/checkout PR branches. Afterward, return the repo to a clean main:

git worktree list            # ensure no stray worktrees
git branch --format='%(refname:short)'   # find leftover PR branches

Before deleting a leftover branch, confirm its commits exist on a remote (no local-only work lost):

git branch -r --contains "$(git rev-parse <branch>)"   # must print an origin/... ref
git branch -D <branch>                                  # then safe to delete

Common Mistakes

• One mega-agent for all PRs → shallow, context-blown. One unit of review per agent.
• Generic rubric → generic findings. Tailor the security angle per PR.
• Reviewing stacked PRs against the wrong base → use each PR's own gh pr diff, note merge order.
• Trusting mergeable/reviews blindly → conflicts clear on rebase; "1 review" is often the author's own. Re-check.
• Accepting test PRs at face value → require a non-vacuity argument.
• Formal approve/request-changes on someone else's PRs without being asked → use --comment.
• jq choking on PR JSON → review bodies contain newlines; query non-body fields, or use --jq server-side.
• Leaving fetched branches behind → always run Cleanup.