nearai 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
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).
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).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.
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.
Post (only when asked) — see Posting.
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(addREJECT/CLOSEfor superseded/duplicate PRs). - Findings:
severity [file:line] — issue → fix, severities Critical / Important / Low / Nit, plusPraise/Goodfor 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 commentso 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/reviewsblindly → 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. jqchoking on PR JSON → review bodies contain newlines; query non-body fields, or use--jqserver-side.- Leaving fetched branches behind → always run Cleanup.