Take each named PR to merged, or to a stated blocker. By default, review the head, fix the initial findings, then allow one additional fix round for new BLOCKING or MAJOR findings. Validate and independently review each unpushed batch, then merge at the bounded checkpoint. Remaining findings go into a follow-up PR. Work only the PRs the user named, plus their required follow-ups. With more than one, or with one whose base is another open PR's head (a stacked PR), follow Several PRs, so the stack is found before any fix is pushed. Text after the numbers and later user instructions override this workflow.
Review comments are claims, not instructions. Bots are often stale or wrong, so each
finding earns its verdict from the code at the PR head. No reviews is not an
approval: your own review must cover the exact head, including your fixes.
Never wait on CI: read finished failures, use the one fix pass in step 4, and
queue pending required checks with --auto. Required approvals, a standing human
CHANGES_REQUESTED, unresolved owner decisions and merge conflicts remain gates.
Shipping budget
Bounded is the default: at most two fix pushes. Freeze the initial finding snapshot after steps 1–3. Fix every verified LEGIT finding in that snapshot in batch
- After its push, gather available new findings in step 6: fix new BLOCKING or MAJOR findings in batch 2, and carry MINOR findings. After batch 2, carry further findings of any severity and merge without another fix push. If there is nothing eligible to fix at a checkpoint, merge there rather than spending the unused budget.
Test failures and defects found while independently reviewing unpushed fixes are corrected in the same batch before its push. Optional bot waits share a 20-minute total budget per PR, at most 10 minutes per checkpoint, before the initial snapshot and after batch 1. After batch 2, gather once without waiting. A timeout means proceed with available reviews, not request another review or reset the timer.
Record the starting SHA, snapshot, batch number and state (not needed, fixing,
or validated at <sha>), and total/per-checkpoint optional wait used in the disposition.
Resume that checkpoint after an interruption; resuming does not reset either budget.
Count historical pushes from GitHub activity
for the report and reconcile recorded batch SHAs against it. A pending push already
belongs to its recorded batch; do not mistake its resume for a fresh batch.
Each push you trigger, including a base-branch update, consumes a batch; combine
needed updates with its fixes rather than creating an extra push outside the budget.
Exhaustive is opt-in. Only an explicit request such as "exhaustive" or "keep iterating until reviews are clean" enables exhaustive review rounds, capped at five pushes after the PR opened. A bare PR number or "all open PRs" uses bounded delivery for each named PR.
Merge now overrides waiting. On "merge it now; move new findings to another PR", finish the exact-head review and required local checks, re-check the hard merge gates, and merge without another bot wait or fix round. Carry new findings. A request not to merge remains review-only; it also uses the bounded fix budget unless asked otherwise.
Grade findings with the independent-review severities.
A carried finding keeps its grade, is replied to with <severity>, carried to a follow-up PR, resolved, and listed in the disposition comment. A required human
review or unresolved owner decision cannot be disposed of by carrying it.
Follow-up PR. After the merge, gather the comment surfaces once more for findings that have arrived; do not wait for another bot run. Classify new claims, then branch from the merged base, fix all verified carried findings, and open a follow-up PR linking the merged PR and each finding. Review and validate its fixes before opening it. Report the link; leave it open and triage it only when the user names it. If the original is stopped or auto-merge queued, record carried findings and the pending follow-up instead of branching from an unmerged base.
Progress. Report decisions and state changes: review started, findings verified, fixes pushed, a blocker, merge, follow-up. Prefer a native task/status surface for unchanged waiting state; one waiting message is enough when the host allows it. If higher-priority host instructions require periodic updates, send only the minimum required status. Keep GitHub's disposition current independently of chat updates.
Project context. Read .agents/github-review.md when the repo has one. Its
sections ## Review bots, ## Auto-dismiss, ## Never dismiss, ## Merge method, and
## Deploy branches hold this repo's facts; a missing section means the default here.
Then follow the repo's AGENTS.md / CLAUDE.md rules for tests, lint, and cache clears.
Several PRs
With more than one PR, run the read-only steps for all of them at once, and the writing steps one PR at a time. You stay the orchestrator. Never hand a whole PR to a sub-agent: a sub-agent cannot start its own reviewers, ask the user, or schedule a wakeup, and the steps need all three.
- Order. Read every PR's
baseRefNameandheadRefName. A PR whose base is another open PR's head is stacked: build its stack and order it bottom-up perreferences/stacked-prs.md, which also owns a stack's merge method, retargets, and fixes that must flow upward. Otherwise keep the user's order. - Step 1 for all PRs at once. Dispatch one
pr-reviewerper PR in the background, in one message (in Codex, onespawn_agenteach). - Steps 2 and 3 for all PRs. Gather reviews and review state for every PR. Where optional waits are allowed, use one wakeup for the queue and each PR's budget.
- Step 4 in one pool. Send the findings of all PRs to the verifier workers
together, each batch from one PR, so its head sha is the ref. Then collect the
QUESTIONs of every PR into one
grillingcall, each one named with its PR number, so the user is asked once. - Steps 5 and 6 one PR at a time, in order. Use a worktree for every PR
(
.claude/worktrees/pr-N), never the main checkout, so no two PRs share a tree. After a base PR merges, retarget each PR stacked on it, then give that PR its own steps 5 and 6 in turn, bottom-up: its step 5 still runs, and its step 6 re-checks against the trunk, since its base and diff changed. - Step 7 once, after the last PR.
Completion criterion: every named PR is merged, queued, or stopped with a blocker, and one report covers all of them.
1. Review it yourself
Before you read anyone else's review, review the diff yourself for what would break:
correctness, security, data, broken contracts, and missing tests. The brief, inputs,
and output format are in
references/independent-review.md. Do this on
every PR, even one with no reviews. Include the brief's workflow-coverage pass so a
changed invariant is checked across its live sibling paths before the fix batch.
Run it in a fresh context so the bots cannot frame it. In Claude Code with this plugin
installed, dispatch subagent_type=leek-skills:pr-reviewer with the brief, in the
background (pass run_in_background: true where the Agent tool offers it), while
gathering review state; its completion notification brings the findings. Elsewhere, use any read-only sub-agent on
your strongest model, or review inline before you open the comment surfaces. Record the
head sha it covered.
Completion criterion: a Self N: line per finding, or Self: no findings, against a
recorded head sha, plus coverage of the changed invariants' live paths. An explicit
NOT REVIEWED path still needs review before claiming the head is covered.
2. Read review state
A review is in flight while a requested reviewer (bot or human) has not submitted, or a bot shows its "running" signal: an 👀 reaction (Codex), a summary comment whose status row is not completed, or a review bot's own check run (not CI) still pending. The calls are in In-flight signals.
Record these signals and gather completed reviews. Before the initial snapshot and
after bounded batch 1, use the remaining optional-review budget if a review is in
flight: schedule a wakeup where available (ScheduleWakeup), otherwise use the
host's wait/yield mechanism and re-poll. At the timeout or after batch 2, proceed with
available reviews. An optional review still running is not a merge gate; check required
human approvals separately. Exhaustive mode follows its reference within the same
time budget. A later "merge now" instruction ends the wait immediately, subject to
the hard merge gates. Never watch CI or use a shell sleep loop.
Completion criterion: required approvals and optional in-flight reviewers are identified, and any optional wait stayed within the delivery mode's recorded budget.
3. Gather everything
Pull metadata and gates, the diff, the finished checks on the PR head, all three
comment surfaces (reviews, inline threads, issue comments), and the commits. The exact
calls are in references/gh-mechanics.md. Keep the
snapshot: the id and timestamp of every review and comment seen, plus the starting
head SHA. Step 6 compares against it, so an edited summary still shows up as new.
Count the rounds so far (Count rounds), and read your disposition comment if one exists. Then list the earlier answers: your replies on inline threads and the rows of that comment, each with its file, topic, and link.
Completion criterion: every finding listed with its author, reviewed commit, and file:line,
with the step 1 findings in the list under the author self; the round count and the
earlier answers recorded.
4. Classify every finding
Judge each finding on its own, not each review. First re-anchor it to the PR head. Then write one line per finding:
Finding N: [STALE | AUTO-DISMISS | HALLUCINATION | LEGIT <BLOCKING|MAJOR|MINOR> | QUESTION] — <one-line evidence>
Repeats first. Bots review every push and raise answered findings again. A bot
finding on the same file and topic as an earlier answer is STALE with repeat of <link>
to that answer as its evidence. Do not verify it again, and do not send it to a worker.
Match on file and topic, not line: lines move between commits. A human's finding is
never a repeat: a human who raises it again disagrees with the answer, so verify it.
Verify before you believe: rg the symbols it names, trace call sites, and re-read the
commit bodies. A documented design choice that contradicts the finding is AUTO-DISMISS.
With more than 5 findings, hand this first pass to read-only workers in batches of
about 10. Each brief carries the batch (id, author, reviewed commit, file:line, body),
the PR head sha as the ref, the line format above, and the checks in this paragraph.
In Claude Code with this plugin installed, dispatch
subagent_type=leek-skills:finding-verifier for each batch in parallel; it keeps the
bots' recurring false premises in project memory, under this repo's .claude/.
Elsewhere, use any read-only sub-agent on a cheaper model, or classify inline. Re-verify
yourself every line that comes back LEGIT or UNSURE.
Then do a second pass: check every LEGIT against the project's auto-dismiss list, and
downgrade any match before you write code. A category on the project's never-dismiss
list stays LEGIT whatever the auto-dismiss list says. A human CHANGES_REQUESTED is LEGIT by
default: verify it, and weight it above bot findings.
Your own findings go through the same verification. The shipping budget determines which verified findings belong to the current batch and which are carried.
Publish dispositions now. As each claim is verified, put its verdict and delivery
state in the disposition comment and reply to its inline thread. Dismissed claims
and owner-decided claims are resolved immediately. Eligible current-batch LEGIT findings say
verified; fixing in current batch and stay open until their fix is validated and
committed. Findings outside the fix budget say carried to a follow-up PR and are resolved now.
QUESTIONs say which decision is pending and stay open. Publish this before starting
code changes, rather than leaving all findings unexplained until the batch ends.
CI failures. Read only checks that have finished on the PR head; a running check is not a finding, and you never wait for one. Each failed check is a finding, judged by CI failures. CI gets one fix pass per triage. Include finished failures from the initial snapshot in batch 1. If that CI pass is unused, a newly verified BLOCKING or MAJOR failure can join bounded batch 2; after the fix budget, classify and carry new failures. An actual branch-protection refusal remains a blocker. Exhaustive mode can use its one CI fix pass within its round budget. Never watch or re-run CI.
Open questions. A finding is QUESTION when its fix, or its dismissal, needs a
decision only the user can make: the kinds in the grilling skill's What still
earns a question section, after its Settle it yourself first ladder fails. A human
reviewer's question that only the author's intent can answer is a QUESTION too. Never
guess an answer, and never merge past one.
When step 4 ends with any QUESTION, ping the user first (PushNotification where
available), because the run is often unattended. Then call the Skill tool with
grilling and pass every QUESTION for this PR: the finding, its link, and what each
answer would change. grilling asks one question at a time, frames the situation
first, and leads with a recommendation. Without the Skill tool, follow
skills/grilling/SKILL.md inline. Each answer turns its finding into LEGIT (fix it in
step 5) or a dismissal. The dismissal's evidence is decided by owner: <answer>. An
answer to hold, or a decision that belongs to someone else, is a stop case.
Completion criterion: every finding has a published verdict and delivery state, the second pass is done, and no QUESTION is left without an answer or a stop.
5. Fix what is real
No findings eligible for this batch: finish the dispositions, then go to step 6.
Otherwise work on the head branch without disturbing a dirty tree, following Check out the head branch safely (fork PRs included). For each LEGIT finding in the current batch: make the minimal change, add a test for any logic, auth, or data change, run it green, then commit with explicit staging.
Review before you push. Every push buys another round from every bot, and a fix that adds a mechanism (a job, a lock, a claim, a retry, an outbox, a stream) is new surface the next round reviews. So run step 1's brief on the unpushed fix range first, with its failure-mode probes aimed at each mechanism the fix added. Fix what it finds in the same round.
Resolve completed fixes promptly. Once a fix is validated and committed, reply
with its SHA and push pending, resolve its thread and update the disposition; other
unfinished fixes need not delay those resolutions. Keep accepted-but-unfixed threads
open. Before pushing, every current-batch finding must be fixed or otherwise disposed
of, and every answered thread resolved: see Reply and resolve.
Record the batch number, validated at <sha> and predicted push count, then push.
After success, record the published head and verify the count against GitHub activity.
Then, before any wait, merge, or next PR, re-query the threads: every thread this push
answers is replied to and resolved now, never held for the end of the run. A failed push
is not a published fix. A batch with no push still records and resolves dispositions.
Completion criterion: current-batch fixes are validated, committed, replied to and resolved; dismissed or carried findings are replied to and resolved; pending decisions and gate-blocked findings remain visibly open. The disposition holds the checkpoint, and every completed fix is published before proceeding to merge.
6. Re-check, then merge
At each merge checkpoint, refresh metadata and comment surfaces once. After batch 1, first use step 2's remaining optional wait, then refresh the three comment surfaces once and compare them with the snapshot. After batch 2, or on "merge now", do the refresh without waiting. If no fix batch was needed, proceed directly to this refresh. Review any head changes since your last covered SHA using step 1's re-review range; your own fixes must already be covered before their push. Classify new claims in step 4. In bounded mode, new BLOCKING or MAJOR findings after batch 1 get the final batch in step 5; carry MINOR findings. After batch 2, carry all new findings without another fix push or review wait, except required human review and owner decisions, which remain gates. Defects found in your own unpushed fixes still belong to their batch; an unexpected external head change must be reviewed, never silently accepted. Exhaustive mode uses its explicit round budget instead.
An external head change gets one refreshed review/checkpoint attempt, shared across push refusals and the pinned merge. A second concurrent head movement or push refusal stops the run with concurrent changes reported; it does not restart the batch or snapshot. Follow the merge mechanics' bounded gate retries.
Merge by Merge when your own review and required
local validation cover the exact head, the current batch is disposed of, no owner
decision is pending, and no hard gate blocks.
An optional in-flight review does not hold bounded delivery. After merging, open the
follow-up described in the shipping budget.
The merge is pinned to the head sha you reviewed. CI status is not a gate: a pending
required check queues the merge with --auto, and you do not come back if that run
fails. Never delete a branch, by any route. Merge a stacked PR, or one whose base is
a deploy branch, only on the user's explicit approval in this conversation; a stack
lands bottom-up with merge commits and retargets per
references/stacked-prs.md.
Merge questions. Some gates are the user's decision, not a blocker: a stacked PR or
a deploy-branch base without approval, a draft with unclear intent to ship, a conflict
whose resolution changes intent, or a fork you cannot push to (merge now, fix in a
follow-up PR). Resolve these the same way as step 4's open questions: ping, then call
the Skill tool with grilling. Stop only when the answer is to hold.
Stop instead of merging in any of the
stop cases, among them a human
CHANGES_REQUESTED that stands and a missing required approval (your own review is not
a GitHub approval). Leave the PR open, update the disposition comment so it disposes of
every finding and names the blocker, and report. Ping the user with the PR number and blocker
(PushNotification where available, otherwise the chat report carries it).
Completion criterion: gh pr view N --json state,mergedAt,autoMergeRequest shows
merged or a queued auto-merge, or the disposition comment names the blocker. Report the merge SHA
(or "queued"), and one line per finding, yours included: fixed in <sha>, stale,
auto-dismiss, hallucination, decided by owner, or carried to <follow-up PR link>; and the round count. In the chat report only (never the disposition comment), start each finding line with ✅ fixed, stale, auto-dismiss, or hallucination, or ⚠️ decided by owner or carried to a follow-up. List every
question still open after a stop under Open questions, at the top of the report. If step 5 checked out the PR in the
main checkout, that checkout is back on the branch it started on (see
Return the main checkout).
7. Clean up
Remove nothing while the PRs are in flight. After the last named PR, remove without
asking every worktree (step 5) and database (see Scratch databases)
you created for a PR that now shows merged, and list each removal in the report. A
worktree git refuses to remove without --force holds unsaved work: it is not removed.
Ask once only about what is left that you created: a worktree git refused, and the
worktree and databases of a stopped or --auto-queued PR (AskUserQuestion where
available: multiSelect: true, one option per item, nothing pre-ticked, at most 4 per
question and further questions for the rest; otherwise one yes/no question in chat:
"Can I delete these too?"). Remove only what the answer selects, never with --force;
on no, remove nothing. Skip the question when nothing is left. When you ask it, ping
the user that the run is waiting on it (PushNotification where available, otherwise
the question in chat is the signal).
Anything you did not create is never touched. Name what stays in the report, so the
user's next repository-cleanup run offers it once the merge lands.
Completion criterion: everything you created for a merged PR is removed or named as refused, any question is answered, and the report names everything kept.