/pr-review — one-shot read-only PR review

Dispatch the pr-reviewer agent at a PR and report what came back. It never applies a finding, never pushes, and never resolves a thread. Why each choice below exists: references/design-rationale.md.

Contents

• Operations
• Before Step 0: on a Dash0 Agent0 host
• Step 0: Parse the argument · Step 1: Resolve the PR
• Step 2: Dispatch the agent · Worker preamble · When sub-agent dispatch is unavailable
• Step 3: Report
• Repo knowledge the reviewer reads
• Locating the support tree
• Hard rules

Operations

Parse the first token of $ARGUMENTS.

No mode turns this command into an apply pass; a request to fix findings is review-loop or /implement-suggestion (which command). Inside review-loop, --no-feedback is this command's report-only counterpart.

Before Step 0: on a Dash0 Agent0 host

Agent0 cannot dispatch the custom pr-reviewer type, and its import can hold this SKILL.md alone. Settle this before Step 0 and before any dispatch, by file presence and never from a failed dispatch. It governs the review operation; remember dispatches nothing and resolves its tree on its own.

• Prepared — /tmp/workspace/agent-skills/env.sh exists. Source it (. /tmp/workspace/agent-skills/env.sh) in every Bash call; it exports AGENT_SUPPORT, AGENT_SKILLS_ROOT, and AGENT_SKILLS_COMMIT. Read linked files from the install, never from the imported folder: this skill's rules/ and references/ from $AGENT_SKILLS_ROOT/skills/pr-review/, a sibling skill from $AGENT_SKILLS_ROOT/skills/<name>/, and every agents/<path> link from $AGENT_SKILLS_ROOT/<path>. When $AGENT_SKILLS_ROOT/skills/pr-review/SKILL.md differs from the copy you are running, or you cannot compare them, follow the installed copy: the installed copy at $AGENT_SKILLS_COMMIT wins, because the files it links come from that commit. Then make the dispatch substitutions in $AGENT_SKILLS_ROOT/shared/rules/agent0-host.md: pr-reviewer becomes a general sub-agent that reads $AGENT_SKILLS_ROOT/pr-reviewer.agent0.md, and the intent worker's type is general.
• Unprepared — no env.sh, but /tmp/workspace, /tmp/.opencode/skills/, or /tmp/.opencode/agents/general.md exists. This skill does not install. Stop with /pr-review — skipped (Agent0 sandbox not prepared; run /review-loop <PR> --no-feedback, which installs on demand and reviews once). After that install, /pr-review takes the prepared branch.
• Neither — not Agent0. Continue with Step 0.

Step 0: Parse the argument

Everything after the PR reference is a pass-through flag: forward it verbatim and interpret none of it.

# Known agent flags, listed for the argument-hint only — NOT a validation allowlist.
#   --critical --full --depth deep --model sonnet --with a,b,c --no-holistic --no-escalate
#   --no-standards --skip-gates --fix-links

Never validate the flag list. Let the agent reject what it does not know.

Step 1: Resolve the PR

case "$ARGUMENTS" in
  *github.com/*/pull/*|*\#[0-9]*) PR_REF="<the reference as given>" ;;
  *) PR_REF=$(gh pr view --json url -q .url 2>/dev/null) ;;   # current branch's open PR
esac

If no reference was given and the current branch has no open PR, stop with one line:

/pr-review: no PR reference given and no open PR on this branch. Pass a URL or #<n>, or open a draft PR first (/create-pr).

pr-reviewer has no PR-less mode. Where gh is unavailable, resolve the reference with mcp__github__pull_request_read instead; a missing gh is never a reason to skip the review.

Step 2: Dispatch the agent

pr-reviewer is an agent, not a skill.

✅ RIGHT — through the harness's sub-agent dispatch tool
Task(subagent_type="pr-reviewer", prompt="<PR_REF> <pass-through flags>")

❌ WRONG — there is no skill by that name; this errors with `Unknown skill: pr-reviewer`
Skill("pr-reviewer", …)

The dispatch tool is named Task in the Claude Code CLI and Agent in the Claude Agent SDK harness behind Claude Code on the web; use whichever this session exposes — any tool taking a subagent_type parameter is it. Dispatch once; iterating against fixes is review-loop's job.

Prepare once, then send the intent worker in the same message when the budget says hybrid.

1. Settle dispatch availability first: a skip must not leave a prepared workspace behind. Pick a run directory, <scratchRoot()>/review-<PR number>-<unix seconds>/, and create it. Resolve $AGENT_SUPPORT per Locating the support tree.
2. Read the PR-state record exactly as the agent's Step 0.7 does — mcp__lorekit__memory_read, scope branch::<owner>/<repo>::<headRefName>, key ci-state::pr-review-<n> — and save a hit to <dir>/state.json. Skip it under --isolated; on a miss, or with no LoreKit tool, pass no --state.

3. Run prepare once, forwarding only the pass-through flags it takes (--full, --effort, --depth, --thoroughness, --finder-passes, --impact-image, --with, --isolated, --pin-head, --repo-dir; add --review-sha <sha> --isolated when the pass-through flags carry --review-sha), and read the topology on the same command. Never forward --model: it is a dispatch setting this skill applies in step 4, and prepare exits 2 on an argument it does not know. A bad flag or flag combination exits 2 here, before any model turn: report prepare's message and stop.

   node "$AGENT_SUPPORT/pr-reviewer/scripts/prepare-review.mjs" --pr <PR_REF> --out <dir>/context.json [--state <dir>/state.json] <prepare flags> \
     && jq -r '.budget.topology' <dir>/context.json && node "$AGENT_SUPPORT/pr-reviewer/scripts/review-telemetry.mjs" dispatch --run-dir <dir> \
     && mkdir -p <dir>/intent && date +%s > <dir>/intent/dispatched_at

   Write whole seconds (%s); BSD date has no %N. When the repo asked for a second finder pass, stamp it too:

   if [ "$(jq -r '.budget.finderPasses // 1' <dir>/context.json)" = 2 ]; then mkdir -p <dir>/pass2 && date +%s > <dir>/pass2/dispatched_at; fi

4. Pick the models once ($AGENT_SUPPORT/pr-reviewer/rules/arguments.md, § The model axis):

   • the reviewer's model is --model when given, else none (the agent's own model: opus);
   • the workers' model is jq -r '.reviewConfig.models.workers // empty' <dir>/context.json, else none.

   Pass a chosen model as the dispatch tool's model parameter on that dispatch only. When the dispatch tool has no model parameter, dispatch without one and print models: not applied (<role>) under the report's run line; never invent another mechanism.

   On hybrid, in one message, dispatch both:

   • pr-reviewer with <PR_REF> <pass-through flags> --context <dir>/context.json --intent-from <dir>/intent/intent.json, then a new line INTENT_WAIT: followed by the wait command below with <dir> and $AGENT_SUPPORT already resolved to absolute paths. The worker runs beside the reviewer, so the file does not exist when the reviewer starts; the reviewer runs this line at its Step 2.6b, after verifying its own candidates, replaces <N> with its own running tool-call count (the only part the caller cannot know), and never replaces the line with ls or cat:

     node "$AGENT_SUPPORT/pr-reviewer/scripts/review-telemetry.mjs" step intent-wait --attr tool_calls_so_far=<N> --run-dir <dir>; node "$AGENT_SUPPORT/pr-reviewer/scripts/review-telemetry.mjs" worker intent import --from <dir>/intent --done <dir>/intent/intent.json --wait 540 --run-dir <dir>; cat <dir>/intent/intent.json

   • a general-purpose worker (the harness's general sub-agent type) with the worker preamble, told to read <dir>/context.json, finders.md, and the review packet the context names, act as the intent finder only, and write its candidates to <dir>/intent/intent.json as a JSON array. It never runs prepare-review.mjs.

5. On in-context (the budget's topology, e.g. a lean quick routing or a small incremental re-review) — dispatch pr-reviewer alone with --context <dir>/context.json, and no worker. 5b. When budget.finderPasses is 2, add two more general workers to the message from step 4 or 5, whichever topology: both get the worker preamble and <dir>/context.json, and neither runs prepare-review.mjs.

   • intent-2 acts as the intent finder only and writes <dir>/pass2/intent.json;
   • other-finders-2 runs every other finder budget.finders turns on, from finders.md (plus finder-consumer-impact.md and finder-dependency.md when those are on), and writes <dir>/pass2/others.json.

   Pass the reviewer nothing extra: it finds <dir>/pass2/ beside its --context file and unions both passes; finalize.mjs names any pass-2 unit that never delivered (agents/pr-reviewer/rules/dispatch-topology.md § Two finder passes).

6. When every dispatch has returned, release the workspace: you ran prepare, so the cleanup is yours, never the reviewer's.

   node "$AGENT_SUPPORT/pr-reviewer/scripts/prepare-review.mjs" --cleanup <dir>/context.json

If prepare exits non-zero, dispatch pr-reviewer alone with no --context: it runs prepare itself, owns that workspace's cleanup, and runs intent in-context. The agent reads the intent file only after verifying its own candidates, and runs intent itself if the worker failed (dispatch-topology.md § The two topologies).

✅ RIGHT — prepare once, then one message, two dispatches
Task(subagent_type="general-purpose", prompt="<worker preamble> … read /…/context.json … act as the intent finder … write /…/intent/intent.json")

Task(subagent_type="pr-reviewer", prompt="<PR_REF> --context /…/context.json --intent-from /…/intent/intent.json\nINTENT_WAIT: node /…/review-telemetry.mjs step intent-wait --attr tool_calls_so_far=<N> --run-dir /…; node /…/review-telemetry.mjs worker intent import --from /…/intent --done /…/intent/intent.json --wait 540 --run-dir /…; cat /…/intent/intent.json")

❌ WRONG — no INTENT_WAIT line: a reviewer that runs `ls /…/intent` once sees an empty directory, reads it as "the worker failed", and finishes without the intent candidates
❌ WRONG — the worker in a second message: the reviewer's wait becomes the worker's full runtime
❌ WRONG — a worker told to run prepare-review.mjs: a second set of GitHub reads, and a leaked worktree

Worker preamble — the intent worker

The intent worker Step 2 dispatches gets this preamble prepended to its prompt, verbatim:

You are the intent worker for one pr-reviewer run, not the full pr-reviewer agent.
- Read ONLY the file(s) named below, by their ABSOLUTE path — never a bare relative path; your
  cwd is not guaranteed to be this repo's checkout.
- Do NOT read agents/pr-reviewer.md. It is the full agent's own document; you are one finder of
  its pipeline, dispatched with exactly the context that finder needs, and reading it would
  re-derive context the dispatch already isolated you from (and burn the tokens doing it).
- Do NOT call Skill(). Read the rule file(s) you were given instead.
- Do NOT run prepare-review.mjs. The context file you were given is already prepared; read
  context.packet.path from it.
- Read the review packet first (context.packet.path): the PR description and every hunk widened
  against the head file, with head line numbers you cite directly. Open a workspace file only for
  what it does not show — a caller, a definition, or a file its index marks "listed".
- Write your JSON output to the path you were given. Return ONLY that path in your final message
  — never the payload inline. The reviewer reads the file from disk; a payload returned as text
  spends context neither side needs to spend.

When sub-agent dispatch is unavailable

Conclude this by capability — no available tool dispatches a sub-agent under any name — never from the absence of the name Task. Then report the skip and stop:

/pr-review — skipped (sub-agent dispatch unavailable; pr-reviewer requires it).

Do not play the reviewer role in this context, and do not retry the dispatch. Where another process reviews the PR instead (a review bot, a CI-triggered agent), the supported path is /implement-suggestion <PR> --watch.

Step 3: Report

The agent posts its own sticky report comment and inline findings. This skill adds a terminal summary and nothing else — never a second GitHub write.

/pr-review on PR #<n> (<owner>/<repo>)

Verdict: <PASS | WARN | FAIL>
Run mode: <full | incremental | incremental-quick | zero-delta> · <deep | standard | quick> · <checkout | tarball | diff-only>
Findings: <N inline (<K> blocking)>, <D deferred (low-confidence, advisory)>
Gates: <one line naming any non-passing gate, or "all passing">

<one line per blocking finding: path:line — the ask>

Report: <URL of the sticky comment>
Apply these: /implement-suggestion <PR>   (or Skill("review-loop", "<PR>") to converge)

Surface blocking findings and non-passing gates prominently — this summary is the only place the result reaches the user. Report the verdict as returned: never soften a FAIL or upgrade a PASS.

Repo knowledge the reviewer reads

When a user asks how to give the reviewer knowledge of their repo, answer with this table; every row is read automatically, with no flag.

<!-- ✓ services/query/REVIEW.md — a fact the code cannot show -->
- The query service reads only from replicas; ingest owns the primary, so any write here is a bug.

<!-- ✗ an instruction: REVIEW.md is context and never changes what the reviewer reports -->
- Don't comment on error handling in this folder.

Locating the support tree

The scripts live in the pr-reviewer agent's support tree, not in the repository you are standing in, so a bare node agents/… exits MODULE_NOT_FOUND everywhere but this skill's own repository. Resolve it in the same Bash call that uses it — Agent0 exports it from env.sh; elsewhere resolve it the way the agent does (its § Locating this agent's own files):

[ -f /tmp/workspace/agent-skills/env.sh ] && . /tmp/workspace/agent-skills/env.sh   # Agent0: exports AGENT_SUPPORT
if [ -z "$AGENT_SUPPORT" ]; then
  resolve() {  # portable readlink -f
    [ -e "$1" ] || return 1
    ( cd "$(dirname "$1")" && t=$(basename "$1")
      while [ -L "$t" ]; do d=$(readlink "$t"); cd "$(dirname "$d")" || return 1; t=$(basename "$d"); done
      printf '%s/%s\n' "$(pwd -P)" "$t" )
  }
  AGENT_MD=$(resolve "${CLAUDE_AGENT_FILE:-$HOME/.claude/agents/pr-reviewer.md}" \
    || resolve "$(agent-skills-root 2>/dev/null)/agents/pr-reviewer.md" || echo "")   # plugin: bin/agent-skills-root
  AGENT_SUPPORT="${AGENT_MD%/pr-reviewer.md}"
fi

Hard rules

• Read-only, always. Never edit a file, commit, push, resolve a thread, or write to GitHub — the agent posts its own sticky report and inline findings.
• One prepare, one review dispatch per invocation, plus the intent worker in the same message when the budget is hybrid, and the two pass-2 workers when budget.finderPasses is 2. Do not loop. The caller that ran prepare runs --cleanup.
• Absent sub-agent dispatch is a skip, not a fallback — and it is a capability test, not a name test. Never review in this context and label it a pr-reviewer review, and never retry the dispatch.
• Never re-adjudicate the verdict. Report PASS / WARN / FAIL as returned, with the blocking findings named.
• remember writes an fp-keyed rule with explicit: true, or asks — never an invented key — and never suppresses a standards or (blocking) finding (rules/remember.md).