Skip to content
cross-review

review-pr

review-pr reviews a pull request or branch written by someone else: a teammate, a contributor, or another agent session. You and the reviewer model (Codex CLI by default) review it independently, debate the differences, and produce one review with a merge recommendation. The skill edits nothing in the project and does not commit, push or check out the pull request in your working tree.

For your own pull request before you merge it, use review-impl in branch mode. That skill fixes what it finds; this one does not.

When to use it

Section titled “When to use it”
  • A pull request opened by a teammate or a contributor.
  • A branch someone else pushed, which you want reviewed before it is merged.

Invoke it

Section titled “Invoke it”
/review-pr 412

Pass the pull request number, or a branch name with its base. Add what you want from the review in plain words, for example “focus on the migration and the auth change”.

What it works out by itself

Section titled “What it works out by itself”
  • The pull request. On GitHub it reads the title, body, base branch, head commit, commits and files, plus the comments that already record decisions. It fetches the base and the pull request head without checking anything out.
  • The base and the head. BASE_BRANCH is the branch the pull request merges into. HEAD_REF is the head as a commit ID, so every round reviews the same version even if the author pushes more commits. Both are checked as real commits.
  • Running the code. When tests or a build are needed, the skill creates a detached worktree outside the repository at the head commit, names it in the session context, and removes it when the review ends.

Round by round

Section titled “Round by round”
  1. Start. It calls review_begin with the title, the description (including linked issues), the base, the head, your review request and the session context.
  2. Analyze alone. Before it reads any reviewer output, it works through the returned analysis_prompt, and writes its numbered findings (FINDING-N) to analysis.md in the session folder.
  3. Wait and compare. When the reviewer’s round is ready (next: cross_check), the skill maps each of its findings to the reviewer’s issues (ISSUE-N) about the same problem. It lists agreements, disagreements (whether the point is real, its severity, and whether it blocks merge) and points only one side raised. A disputed point is checked in the code before it is argued.
  4. Decide the next step.
    • Consensus: review_end with outcome: "consensus", once both sides agree on every blocking finding.
    • Stalemate: review_end with outcome: "stalemate", when the same disagreement repeats for two rounds, or when the runner reports a stalemate (next: done).
    • Otherwise: review_reply with the agreed points, the disagreed points, and the new findings. Then it waits again.

A point the reviewer raises without evidence is not a reason to change a finding. The skill concedes only for evidence or an argument it had not weighed, and names the point.

The report

Section titled “The report”

The report leads with the merge recommendation:

  • Request changes if any agreed finding blocks merge.
  • Approve, with the non-blocking findings as comments, otherwise.
  • On a stalemate over a blocking point, both sides are presented and you decide.

Then come the blocking findings, the non-blocking ones, the disagreements as a table (point, the skill’s view, the reviewer’s view), and what was not checked (tests not run, files skimmed). The report is drafted the way you would post it: a summary, plus one comment per finding at its file:line, in the pull request’s language. It is written to summary.md in the session folder.

The skill posts to the pull request only when you ask it to.

What you can say in chat

Section titled “What you can say in chat”
You say Effect
“Use model X” or “effort high” The model or effort is passed to the reviewer, and remembered for later rounds
“Skip the review” The review stops and the record shows you skipped it
“Stop” The session stops; you can resume it later
“Post the comments” The draft comments are posted to the pull request, one per finding
“Accept it as approved” The result is recorded as your decision, not the reviewer’s

Example

Section titled “Example”

Project: orchard-api. A contributor opens pull request 412, which adds a retry for failed webhook deliveries.

  • Round 1: the skill’s analysis finds that a retry after a timeout can deliver the same event twice (FINDING-1, high). It also notes that the new config key has no default in the docs. The reviewer raises the duplicate delivery as ISSUE-1 and adds a point about a missing test for the backoff cap. The skill checks the backoff code, confirms the cap is applied, and drops the point as a disagreement with evidence.
  • Round 2: the reviewer accepts the dropped point and agrees on the duplicate delivery. Both sides agree that it blocks merge.
  • Consensus: the recommendation is request changes. The report lists the duplicate delivery as the blocking finding, the missing docs default as a comment, and states that the tests were not run.

The skill drafts the comments. You decide whether to post them.

See review-impl for reviewing your own changes before a merge, and review-think for a debate on a question that is not a pull request.