pr-review

What this skill does

# PR Reviewer

Run a comprehensive PR review covering all four Freenet review perspectives, plus an
external (non-Claude) model, and post a consolidated review to the PR.

## When to Use

Invoke `/freenet:pr-review <PR-NUMBER>` after a PR is ready for review, before merging.
The PR number is passed as the skill argument (`$1`); if none is given, detect the PR
for the current branch with `gh pr view --json number -q .number`.

## How This Skill Works

This skill **orchestrates** a review — it does not do all the perspectives by hand.
It checks out the PR, triages the change to a risk tier, spawns specialist subagents
in parallel (scaled to that tier) plus an external model pass, reconciles their
findings into one report, and posts that report to the PR.

The four subagents ship with this plugin as first-class agent types — invoke them
directly with the `Agent` tool's `subagent_type` parameter. Do **not** paste agent
definitions into a `general-purpose` prompt; that is obsolete.

## Step 1: Check Out the PR, Gather Context, and Triage Risk

**Critical:** reviewers must read the PR's *actual code*, and the review must not
disturb the user's working tree. Check the PR out into a **dedicated worktree** — do
NOT use `gh pr checkout`, which switches the user's working branch and drags any
uncommitted changes onto the PR branch, contaminating the review.

```bash
PR=<PR-NUMBER>          # the $1 skill argument
BASE="$(gh pr view "$PR" --json baseRefName -q .baseRefName)"   # the PR's base branch

git fetch origin "$BASE"                 # fresh base branch for the diff
git fetch origin "pull/$PR/head"         # PR head — FETCH_HEAD now points here
REVIEW_DIR="${TMPDIR:-/tmp}/pr-review-$PR"
git worktree remove --force "$REVIEW_DIR" 2>/dev/null || true   # prune a stale prior worktree
git worktree add --detach "$REVIEW_DIR" FETCH_HEAD              # PR code, isolated
cd "$REVIEW_DIR"                                                # run the review from here
```

Gather context (from the worktree):

```bash
gh pr view "$PR"
gh pr diff "$PR" --name-only
gh pr checks "$PR"                    # CI status
gh issue view <ISSUE_NUMBER>          # linked issue (from "Fixes #" / "Closes #")

# Existing review feedback — read it so the review ADDRESSES it, not duplicates it:
gh pr view "$PR" --json comments,reviews
gh api repos/{owner}/{repo}/pulls/"$PR"/comments   # inline review comments
```

The `gh api .../comments` call above is the reliable way to get inline comments —
they are easy to miss. (If your environment provides a `gh-pr-interactions` skill, it
documents the comment API in more depth.)

**Large diffs:** if the diff exceeds ~2000 changed lines or ~40 files, instruct each
subagent to review by file batches rather than loading the whole diff into context.

**Cleanup (mandatory — do this even if the review aborts partway):** remove the
worktree with `git worktree remove --force "$REVIEW_DIR"`.

Do NOT run a code-simplifier or any other mutating step here — this skill reviews the
PR as submitted; editing the checked-out code would make reviewers judge something
other than the PR.

### Pick the Risk Tier

Choose the tier by checking these in order — **first match wins** — or honor an
explicit tier the user named (e.g. "full review of PR 42"):

1. **Skip** — the *entire* diff is mechanical: typo / comment-only / formatting /
   version bump / CHANGELOG-only. Judge this against the whole diff, not the PR title —
   a PR labelled "version bump" that also edits logic is **not** Skip. Report
   "trivial — CI is the only gate" and **stop**; do not spawn reviewers.
2. **Full** — the change touches a high-risk surface (below), OR the diff is large or
   cross-cutting, OR you are genuinely uncertain. Run the complete process.
3. **Light** — everything else: a low-to-moderate-risk change with no high-risk
   surface. Spawn a reduced reviewer set (Step 2) plus the external model pass (Step 3).

These tiers are exhaustive — Light is the catch-all. When torn between two, pick the
heavier one.

**High-risk surfaces — always Full:** concurrency / async, cryptography / security /
auth, state authorization, data or schema migration, wire format / protocol /
serialization (freenet-stdlib enums), consensus / routing, transport / NAT traversal,
contract or delegate WASM, deploy / release / CI config.

State the chosen tier and the one-line reason before proceeding.

## Step 2: Spawn the Review Subagents in Parallel

Spawn the reviewers with the `Agent` tool in a **single message** so they run
concurrently, each with `run_in_background: true`. Which reviewers run depends on the
tier picked in Step 1:

- **Full** — spawn all four.
- **Light** — spawn `freenet:skeptical-reviewer`; also spawn `freenet:big-picture-reviewer`
  if the diff removes code or spans multiple components.

| `subagent_type` | Perspective |
|-----------------|-------------|
| `freenet:code-first-reviewer` | Reads the code before the description; flags gaps between stated intent and implementation |
| `freenet:testing-reviewer` | Test-coverage gaps at unit / integration / simulation / E2E levels |
| `freenet:skeptical-reviewer` | Adversarial — bugs, race conditions, edge cases, failure modes |
| `freenet:big-picture-reviewer` | Goal alignment, removed tests/fixes, scope creep, stale skills/docs |

These `subagent_type` values are plugin-namespaced: `freenet:` is the plugin name and
the files in `agents/` carry the bare name (`skeptical-reviewer`, etc.). Use the
`freenet:`-prefixed form exactly as shown.

In each subagent's prompt, include: the PR number, the repo (`owner/repo`), and the
path to the review worktree from Step 1 (`$REVIEW_DIR`), so the agent can `Read`/`Grep`
the PR's actual code — not just the diff — for surrounding context. Each agent already
carries its own review methodology; you do not need to supply it.

## Step 3: External Model Review (runs concurrently with Step 2)

Run this for **both Light and Full** tiers — the external model is the highest-value
single pass, because its blind spots do not correlate with Claude-authored code.
Spawn it concurrently with Step 2's subagents. Run a non-Claude model from the review
worktree, diffing against the PR's base branch (`$BASE`, fetched fresh in Step 1) —
never a possibly-stale local `main`:

```bash
codex review --base "origin/$BASE"
```

(If your environment provides a `codex-review` skill, it wraps this command.) For a
Full review of a high-risk PR, add a third independent model when one is available —
e.g. a `gemini-cli-review` skill or the `gemini` CLI.

## Step 4: Freenet Bug-Pattern Check

Do this for **Full** reviews, and for **Light** reviews whose change has non-trivial
logic.

When reviewing **freenet-core**, the canonical and continuously-updated bug-pattern
list lives at `.claude/rules/bug-prevention-patterns.md` in that repo. Read it and
check the PR against every pattern listed there — it supersedes any snapshot in this
skill or in the subagent definitions.

Recurring patterns (non-exhaustive — the in-repo file is authoritative): `biased;`
select starvation, fire-and-forget spawns, incomplete state cleanup on failure,
backoff without jitter, `.send().await` on bounded channels inside event/recv loops,
protocol-enum / wire-format breaks for older consumers, paired `Option` fields that
must co-occur, and manually-mirrored telemetry counters that rot after op migrations.

## Step 5: Synthesize — Reconcile and Verify

When all spawned subagents and the external model pass have returned, **do not just
concatenate their reports.** Synthesize:

1. **Deduplicate** — the same finding will surface from multiple reviewers; merge it
   into one entry.
2. **Reconcile contradictions** — if two reviewers disagree, investigate the code
   yourself and decide; note the disagreement in the report if it is genuinely open.
3. **Verify before reporting** — subagents and Codex can cite wrong line numbers or
   hallucinate. Open every cited `file:line` and