Pr Review

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

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:

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.