| name | pr-review |
| description | Targeted, read-only review of a PR or checked-out branch. Acquires the diff (a PR number, or the current branch vs origin/master), shards the changed material into appropriately sized, randomized chunks, and spawns multiple read-only code-review and library-consumer sub-agents in parallel (one per shard), then aggregates and de-duplicates their findings into a single report with severity and a valid / already-fixed / invalid verdict for each. Read-only — it does not edit files, commit, push, or touch the GitHub PR conversation. The review sub-agents default to Sonnet but can be overridden per run (e.g. to opus). Use when asked to "review this PR", "review the branch", "what's wrong with this diff", "do a code review", or "review with opus". For the full review → fix → push → resolve loop, use `pr-cycle` (which delegates its review step here). |
| allowed-tools | Bash, Read, Agent |
PR Review
Produce a fresh, read-only review of a PR or a checked-out branch and report the
findings. This is the "review" half of the PR workflow, extracted so it can be run
on its own. The orchestrator skill pr-cycle calls this skill to obtain its local
findings, then goes on to address, push, and resolve them.
Scope — what this does and does not do
Does: acquire the diff, shard it into appropriately sized chunks, spawn the
read-only review sub-agents (one per shard, multiple of each type), evaluate and
de-duplicate their findings, and report them with severity and a verdict.
Does NOT: edit files, run make ci, regenerate the README, commit, or push; and
it does not interact with the GitHub PR conversation — it does not read existing
PR comments/threads, resolve or minimize them, edit the PR body, or re-request
Copilot review. Those belong to pr-cycle. This skill only generates a fresh
agent-based review of the code itself.
This skill is purely advisory: its output is a findings report for a human (or for
pr-cycle) to act on. It applies no changes.
Model tiers
| Tier | What | Step | Model |
|---|
| 1 — cheap delegation | Read-only review sub-agents, one per shard | 3 | Sonnet (pinned in agent def; overridable per-run, e.g. to opus — see Input) |
| 2 — judgment core | Shard the material; de-duplicate and classify findings into valid / already-fixed / invalid | 2, 4, 5 | session model (use Opus) |
Input
A target and an optional review-agent model override, in any order.
- Target: either a PR number, or nothing (review the current checked-out
branch). If a PR number is omitted you may infer one from the current branch with
gh pr view --json number (run with the sandbox disabled — see below), but a PR is
not required: a plain checked-out branch is reviewed by diffing against
origin/master.
- Review-agent model: the model used by the two reviewer types (
pr-code-reviewer,
pr-consumer-reviewer) defaults to sonnet, but can be overridden. If the input
names a model (e.g. "review with opus", "opus reviewers", "model=opus"), pass that
model to the Agent tool's model parameter when spawning all shard sub-agents in
step 3. With no override, omit model so each agent uses its pinned Sonnet default.
- Shard sizing (optional): by default the orchestrator sizes shards automatically
from the review-agent model — smaller shards for cheaper models, larger for stronger
ones (see step 2). Override with an explicit target in the input if you want finer or
coarser splitting, e.g. "shards of ~4 files", "one file per shard", or "single shard"
(the latter restores the old whole-diff-per-reviewer behavior).
Announce the resolved target and review-agent model at the start — e.g. "Reviewing
the current branch with opus reviewers" or "Reviewing PR #264 with Sonnet
reviewers" — before spawning anything. After sharding (step 2), announce the shard
counts (e.g. "3 code shards, 2 consumer shards") before spawning the reviewers.
Steps
1. Acquire the diff and build the review inventory
The diff is git diff origin/master, which works for any checked-out branch whether
or not it has a PR:
git diff origin/master
git diff origin/master --stat
If you are targeting a specific PR, the pr-cycle helper prints the identical diff
and is equivalent (.agents/skills/pr-cycle/pr.py PR_NUMBER diff).
From the changed-file list, build an inventory of review units. A unit is normally
one changed file, with one exception: keep atomic couplings together as a single
unit — a trybuild tests/ui/<case>.rs and its matching <case>.stderr (and any paired
source) must travel together, since reviewing one without the other is meaningless.
Tag each unit with the reviewer type(s) it needs:
- Code-review set — all code:
cached_proc_macro/src/, src/, tests/, examples.
Essentially every changed .rs file and golden file.
- Consumer-review set — public-facing surface only:
src/lib.rs, the public APIs in
src/stores/, cached_proc_macro/src/lib.rs (the macro attribute surface),
README.md, CHANGELOG.md, docs/migrations/, and examples/. Internal macro
plumbing and internal test helpers are not consumer-relevant.
A unit may belong to both sets (e.g. src/lib.rs).
2. Shard each set into appropriately sized, randomized chunks
The code set and the consumer set are sharded independently. Sharding has two jobs:
keep each shard small enough that the review model attends to every line, and vary the
grouping between rounds so repeated reviews surface different findings.
a. Pick the target shard size from the review-agent model. Cheaper models get
smaller shards; stronger models absorb more per shard without losing attention:
| Review model | Target per shard |
|---|
| sonnet (default) | ~600-900 changed diff lines, or ~4-6 units |
| opus | ~1500-2500 changed diff lines, or ~10-15 units |
An explicit shard-size override from the Input wins over this table. Use the
--stat line counts from step 1 for packing.
b. Randomize the grouping, then pack. Produce a fresh random ordering of the units
each run — shuf reseeds from the OS on every invocation, so each round yields a
different permutation:
git diff origin/master --name-only | shuf
Pack the shuffled unit list greedily: add units to the current shard until adding the
next would exceed the target size, then start a new shard. Because the order is
reshuffled every round, a given file lands with different neighbors each time — reviewers
see different cross-file context and surface different cross-cutting findings. Do not
re-sort the shuffled list into a tidy order; the randomness is the point. (Atomic
couplings from step 1 stay intact as one unit through the shuffle.)
This yields some number of code shards and consumer shards (each typically a handful).
Announce the counts before spawning.
3. Spawn one sub-agent per shard, in parallel
For each code shard, spawn a pr-code-reviewer. For each consumer shard, spawn a
pr-consumer-reviewer. Every agent's prompt must include:
- The target (PR number, or branch name if there is no PR)
- The explicit list of files in its shard
- An instruction to scope its review to those files: acquire its slice with
git diff origin/master -- <files...> and Read those files in full for context, but
report findings only on the assigned files.
- (consumer shards only) a pointer to the current
src/lib.rs doc comments and
README.md for the APIs its files touch.
Both agent types are read-only (no Edit/Write) and carry their full rubrics in their
agent definitions — do not re-specify the rubric in the prompt.
Model override: if the input requested a review-agent model (see Input),
pass it to the Agent tool's model parameter on every spawn (e.g. model: "opus").
With no override, omit model so each agent uses its pinned Sonnet default.
Spawn all shard agents in a single message so they run concurrently, and wait for all
to complete before proceeding. (Harness concurrency is capped; excess agents queue and
still complete.)
4. Evaluate all findings (de-duplicate across shards)
Collect every shard's report. Shards are disjoint, so most findings are unique, but a
cross-cutting issue can be reported by more than one shard (or by both a code and a
consumer reviewer) — merge duplicates into one finding before judging. For each
finding, assign a verdict and explain your reasoning:
- Valid — the concern is real and the code should change.
- Already fixed — the concern was valid in principle but the current code already
handles it (the reviewer was working from a partial view).
- Invalid — the finding is incorrect or environment-specific (e.g. a rustc version
mismatch on trybuild golden files, or a "missing" feature gate that is actually
present).
This verdict pass is the judgment core; run it on the session model (use Opus). Do not
soften or pad — an invalid finding called valid sends pr-cycle (or a human) chasing a
non-issue.
5. Report
Present a single consolidated report:
- The target reviewed (PR number or branch name) and the review-agent model used.
- Sharding: how many code shards and consumer shards ran, and the target shard size
used.
- Code-reviewer findings: total count (after de-dup), broken down by severity
(high / medium / low), and by verdict (valid / already-fixed / invalid).
- Consumer-reviewer findings: the same breakdown.
- For each valid finding: a one-line summary, the
file:line (or area), and why it
matters — enough that pr-cycle or a human can act on it without re-reading the agent
output.
- For each invalid or already-fixed finding: a one-line note on why it was ruled
so.
- A closing one-line verdict: is the branch/PR clean, or are there valid findings to
address (and how many high/medium)?
Do not apply any fix. If the caller wants the findings addressed and pushed, that is
pr-cycle's job.
