/review-pr

name: review-pr
description: Reviews a change (PR/MR) diff against main, posts inline review comments and a summary, then marks it ready for review. Tracker- and host-agnostic — GitHub via gh is the factory default; docs/agents/code-host.md overrides. Use when user says "review pr", "review this pr", "/review-pr", or wants to run automated review on a pull request.

Review PR

Reviews the change's diff, posts the review, marks it ready.

**Contract doc.** Change mechanics come from the repo's `docs/agents/code-host.md` — read that file first if present. The commands below are the **GitHub factory defaults** (`gh`), used verbatim when that doc is absent or confirms GitHub; when it defines a different mechanic for an operation (checkout, read feedback, post review, mark ready), the doc wins. "PR" below means whatever the code host calls a reviewable change.

**Its annexes are deferred, not optional.** `code-host.md` links phase annexes — `code-host-ci.md` above all — with the phase that opens each one spelled out. **Do not read an annex at the start**: open it at the step that names it, and not before. A worker that reads them all up front pays for the whole contract in its first turn to use a quarter of it.

Invoke

/review-pr          # reviews PR for current branch
/review-pr 42       # reviews PR #42

Flow

1. Identify and check out the PR

If no ref given, get the current branch's change metadata — GitHub default:

gh pr view --json number,title,headRefName,baseRefName,state

Refuse if PR is closed or merged.

If the current branch is not the PR branch (the /developer pipeline runs this in a fresh worktree), first confirm **where you are**:

git rev-parse --path-format=absolute --git-dir --git-common-dir   # two different paths = linked worktree

`--path-format=absolute` is not optional. Without it git answers with whatever form is shortest from your cwd, so in the primary checkout's *root* both print `.git` (equal, correct) but from any *subdirectory* they print an absolute path and `../.git` — different strings for the same repo, which reads as "linked worktree" and lets the checkout below run against the user's checkout.

If both paths are equal you are in the **primary checkout** — detaching or switching it would hijack the user's working state. Never do it: as a /developer worker end with `RESULT blocked reason=escaped worktree — refusing to touch the primary checkout`; interactively, stop and tell the user. Only once that command has answered with two different paths, check out the change head detached, per the code-host doc's read-only checkout — as **plain, separate commands**, one per call. GitHub default:

git fetch origin "pull/<PR>/head"
git checkout --detach FETCH_HEAD

**Do not fold the worktree check into the checkout.** The tempting shape — `[ … ] || { echo …; exit 1; }` ahead of `git fetch && git checkout` — is one the worktree sandbox refuses as "too complex to verify", costing three failed calls in every review before you run the bare checkout anyway. Read the `git rev-parse` answer, decide between calls, then run the two commands.

Never `gh pr checkout` — in a linked worktree it fails with `fatal: '<branch>' is already used by worktree` because the PR branch is still checked out in the build worker's worktree. Never `git checkout main` either — `main` is checked out in the primary worktree.

2. Settle the review scope

A PR is reviewed more than once: the fix cycle sends the reviewer back after every fix pass. Re-reading the whole change each time is the most expensive thing in the loop and buys the least — the parts nobody touched since the last review were already reviewed, by this same procedure, and found sound.

So first ask the code host **what revision was last reviewed**, per its read-the-last-reviewed-revision operation. GitHub default:

gh api "repos/{owner}/{repo}/pulls/<PR>/reviews" \
  --jq 'map(select(.state != "PENDING")) | last | .commit_id // empty'

Empty output means nobody has reviewed this PR yet. Then:

git fetch origin main    # local host: skip the fetch, diff against main

• **No previous review** → **full scope**. The review diff is

`git diff origin/main...HEAD`.

• **A previous review, and its sha is an ancestor of HEAD**

(`git merge-base --is-ancestor <sha> HEAD`) **and is not HEAD** → **incremental scope**. The review diff is `git diff <sha>..HEAD`.

• **The sha is HEAD** → nothing has been pushed since the last review. Do not

re-review the same commit: as a /developer worker report `RESULT blocked reason=no new commits since the last review (<sha>)`; interactively, say so and stop.

• **The sha is not an ancestor of HEAD** (force-push, rebase, a review posted

against a branch that was rewritten) → the anchor is meaningless. Fall back to **full scope**.

Under incremental scope, `git diff origin/main...HEAD` is still yours to read as **context** — the surrounding code a new hunk lives in, the function it calls — but findings come from the review diff. A line nobody touched since the last review is not a finding, however tempting: it was reviewed and it passed. What replaces the re-read is the thread check in step 3.

Say which scope you used in the review summary, naming the anchor sha on an incremental one.

Reading that context follows the repo's own method: where the agent docs prescribe a zone map or an index/outline command, use it rather than `cat`, never truncate it or silence its errors, and batch several lookups into one command separated by `echo ===`. Each call costs a whole turn, and a reviewer pays them on top of the diff it came to read.

2b. Read the feedback

Whatever the scope, read the existing feedback and the rendered diff — GitHub default:

gh pr view --comments   # existing comments
gh pr diff              # rendered diff with context

Then locate the **originating spec**: the issue(s) the PR body