Review PR

Triage PRs so the user opens only the ones that need them. The run completes unattended: everything that can be said on GitHub is posted without asking, and the user is interrupted exactly once — at the end, for the judgment calls only they can make.

Every reviewed PR ends on one verdict with a stated confidence, one document, and an evidence ledger recording what was and was not checked.

Two paths through this skill, and the reviewing itself belongs to neither — a sub-agent per PR follows REVIEW.md:

• One PR — review-pr 1443, or a PR the user names.
• All PRs — every open PR against main that is not a draft, not authored by joshunrau, and not a dependency bump by a bot.

Where documents live

Two buckets, and the bucket is the answer to "does this need me?":

misc/pr-reviews/
├── action-required/   CLOSE · REQUIRES_HUMAN_REVIEW · MERGE
└── no-action/         REWORK · BLOCKED · PENDING

action-required/ holds only what the user must personally do — close it, judge it, merge it. Work the author owes is never a reason to file a document here; it goes to the author on GitHub. The user is not a courier.

Three invariants:

• One document per PR, in exactly one bucket. Before writing <N>.md, delete any existing misc/pr-reviews/*/<N>.md. When a settled question changes a verdict, mv the document to the other bucket — never write a second copy.
• Every PR in the set gets a document, gate failures included. BLOCKED and PENDING get a stub in no-action/: number, title, headRefOid, the block reason, and whether a comment was posted.
• No run ends with an unposted action item. Every ## Action items entry in every document, in either bucket, has reached GitHub by step 7.

Every posted body carries its commit

Every body this skill posts — review or comment — ends with:

Reviewed at commit <headRefOid>.

That line is how the skill knows on the next run what it has already said, so it is not optional.

1. Collect the set

gh pr list --state open --base main --limit 100 \
  --json number,title,url,author,isDraft,headRefOid,additions,deletions,changedFiles,mergeable,statusCheckRollup

For a single PR use gh pr view <N> --json <same fields>. A named PR is reviewed whoever authored it and whatever its draft state — the exclusions above shape the batch only.

Done when every PR in the set carries its number, headRefOid, author, size, mergeability and check rollup.

2. Sweep what is finished

For every <N> with a document under either bucket, whether or not it is in this run's set:

gh pr view <N> --json state --jq .state

Delete the document when the state is MERGED or CLOSED. A merged PR is not a to-do.

This runs before the gate so a stale document can never satisfy the cache check below.

3. Gate before spending anything

The gate runs on metadata alone. No fetch, no worktree, no install until a PR passes it.

mergeable: UNKNOWN means GitHub has not computed the merge yet — re-query that PR once before deciding.

A PR whose misc/pr-reviews/*/<N>.md carries a review verdict at the current headRefOid is cached: skip it, spend nothing. A BLOCKED or PENDING stub never suppresses work, however recent — CI may have gone green since it was written.

4. Notify the blocked

No approval, no draft shown to the user. For each BLOCKED PR, first read back what the PR already says:

gh pr view <N> --json reviews,comments --jq '[.reviews[].body, .comments[].body] | join("\n")'

If that text already contains the current headRefOid, stay silent — the author has already been told about this exact commit. Otherwise request changes: name the failing check or the conflict, say what the author should do, say that review resumes once it is green. Facts only — no verdict, no review content, no findings.

gh pr review <N> --request-changes --body-file <path>

GitHub refuses a review on the user's own PR; fall back to gh pr comment <N> --body-file <path> there — the same fallback applies everywhere this skill posts.

Then write the stub to no-action/<N>.md and move on. Blocked PRs never reach the user's attention beyond a count in the final tally.

5. Review, three at a time

Spawn one general-purpose sub-agent per surviving PR, at most three in flight. Each prompt carries: the PR number, URL, title, author, headRefOid, size, the worktree path to use under the scratchpad directory, and this instruction —

Read .agents/skills/review-pr/REVIEW.md and follow it exactly for this PR. Return only the verdict, confidence, the document path, and the reply-body path where there is one.

Setup failing inside a worktree splits two ways, and the split matters:

• pnpm install or pnpm generate:env fails → BLOCKED (machine). Post nothing; the machine is broken, not the PR. Report it to the user directly.
• pnpm lint fails → BLOCKED (PR). The merge result does not typecheck against current main. Request changes asking the author to update their branch, subject to the same headRefOid guard as step 4, and write the stub.

Action items belong to the author, so they go to the author. Never carry one back to the user to relay — that is the user doing the reviewer's errand. As each document lands, post its reply body immediately: no approval, no waiting for the other reviews.

A PR with an outstanding action item is never MERGE. One action item is one round trip, so the verdict is REWORK and the review requests changes. There is no "merge it, and by the way fix these five things" — that hands the user a decision the author has not finished earning, and it buries the items in a comment on a PR nobody will reopen. The corollary binds the other way too: if the only thing standing between a PR and MERGE is a list of remarks that name no real defect and no documented standard, the remarks were never action items and should not have been written.

REQUIRES_HUMAN_REVIEW is the one verdict that waits, and only until step 6: its questions may change its action items, so posting now risks a second review that contradicts the first. It is posted there, minutes later, and never left for the user to pass on.

Closing a PR is the user's call, so gh pr close is never run — CLOSE posts its reply and nothing more.