Polytoken Reviewer Skill

gistfile1.txt

---
name: code-review
description: Review a pull request (or the current branch) with TWO parallel reviewer subagents on gpt-5.5(high) — a standard reviewer and an adversarial reviewer. Merge their findings only after both return; deliver an in-chat summary always and post to the PR only with consent. When reviewing your own branch, iterate on the feedback and re-invoke until no findings remain.
disable-model-invocation: false
tags:
  - productivity
polytoken: true
---

# Code Review

Orchestrate a two-reviewer code review. The main agent does **not** review the diff itself — it dispatches two reviewer **subagents** that run concurrently on `gpt-5.5(high)`, waits for **both** to return, merges their findings, and delivers a single review. When the main agent owns the branch under review, it then fixes the findings and re-invokes this skill until the review comes back clean.

This is the reviewer counterpart to `create-pr` (opens the PR) and `bugbot` (drives an external bot). Here, two of Claude's own subagents are the reviewers.

> **Subagents + model — non-negotiable.**
> - The review reasoning runs **inside subagents, never in the main agent.** Dispatch **exactly two** `general-purpose` subagents in a **single assistant turn** so they run in parallel.
> - Each subagent runs on **gpt-5.5(high)**: pass `model_override: openai/gpt-5.5` (that model defaults to `high` reasoning effort — see `config.yaml`). The skill's standing requirement *is* the explicit operator request that authorizes this `model_override`.
> - One is the **standard reviewer**, one is the **adversarial reviewer**.
> - The main agent only orchestrates: gather context → dispatch the two → wait for both → merge → deliver → (authoring mode) fix + re-invoke.

## Modes — decide this first

- **Authoring mode** — *you wrote the changes under review* (the branch you've been building, or a PR you authored). After the review you **iterate**: fix the findings and re-invoke until clean.
- **External mode** — *you're reviewing someone else's PR.* **Read-only**: deliver feedback, never edit their code, never iterate on their behalf.

If it's ambiguous who owns the changes, ask one clarifying question before reviewing.

## The Loop

```
identify target + mode (authoring | external)
        │
        ▼
gather diff + context  (main agent, any model)
        │
        ▼
dispatch TWO reviewer subagents in ONE turn — parallel, gpt-5.5(high):
   • standard reviewer            • adversarial reviewer
        │
        ▼
WAIT for BOTH to return   ◄── deliver / post / fix NOTHING until both terminal
        │
        ▼
merge + dedupe findings → one severity-ranked review
        │
        ▼
deliver: in-chat summary (always) + post only if open PR & consent
        │
   ┌────┴───────────────────────────────┐
external mode                       authoring mode
   │                                     │
  done                          findings? ──no──► clean — done
                                         │
                                        yes → fix root cause + tests
                                              │
                                              ▼
                                  RE-INVOKE this skill (fresh 2-reviewer pass)
                                  until no new findings  (cap 5 cycles)
```

## Steps

### 1. Identify the target and the mode

- **Target:** a PR number if the user gave one; otherwise the current branch vs. the repo's default base.
  ```bash
  BASE=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name)
  OWNER=$(gh repo view --json owner --jq .owner.login)
  REPO=$(gh repo view --json name --jq .name)
  ```
- **Mode:** *authoring* if you are the author of the changes (your working branch, or a PR whose author is you); *external* if you're reviewing changes you didn't write. Check the PR author if there's a PR:
  ```bash
  gh pr view <PR> --json author,headRefName,state,url --jq '{author:.author.login,state,url}'
  ```
  If ownership is unclear, ask one question. The mode decides whether step 6 runs.

### 2. Gather the diff and context (main agent)

```bash
git fetch origin "$BASE" --quiet
git diff "origin/$BASE...HEAD" --name-only      # changed files
git log  "origin/$BASE..HEAD" --oneline         # commits
git diff "origin/$BASE...HEAD"                    # full diff
gh pr view <PR> --json title,body,url,state,isDraft,baseRefName,headRefName   # if a PR exists
```

Assemble a **context bundle** to hand to both subagents: changed-files list, commit log, the full diff, the PR title/body (intent), and the touched subsystem/prefix (e.g. `discord_smite_ui/` → smite-ui). This is cheap orchestration work — fine on any model.

### 3. Dispatch the two reviewer subagents — parallel, gpt-5.5(high)

In a **single assistant turn**, call the `subagent` tool **twice** (so both run concurrently), `subagent_type: general-purpose`, `model_override: openai/gpt-5.5`. Hand each the full context bundle and tell it: read-only on source (it may read files / run `git diff` to dig deeper, but must not modify code or branch state); return findings as its result in the format below.

**Reviewer A — Standard.** A balanced, thorough review across, in priority order:
1. Correctness & logic (does it do what the PR claims?)
2. Edge cases & error handling
3. Security (injection, authz/authn, secrets, unvalidated trust-boundary input)
4. Concurrency (races, shared mutable state, cancellation)
5. Performance & resource use (N+1s, unbounded growth, hot-path cost)
6. API & compatibility (breaking signatures/schemas, migration safety)
7. Tests (is the new behavior covered? tests that would fail before the change?)
8. Readability & maintainability (nits, lowest priority)
Also call out **what's good**.

**Reviewer B — Adversarial.** Assume the change is subtly broken and *try to break it.* Hunt the worst-case: the exploitable security hole, the race, the malformed/hostile input that isn't handled, the invariant the author assumed but didn't enforce, the edge case the happy-path tests skip. Be skeptical of the tests themselves — do they actually pin the contract, or do they pass vacuously? Prefer one real, well-argued blocker over ten nits.

**Finding format (both reviewers):** a one-line verdict, then each finding as `severity · path:line — problem → why it matters → fix direction`. Severity scale: `Blocker · High · Medium · Low · Nit`. Use the diff's new-side line numbers. No hypotheticals stated as fact — unverifiable downstream effects are marked "unverified".

### 4. Wait for BOTH, then merge (main agent)

- Use `job_block` to wait until **both** subagents are terminal. **Deliver nothing, post nothing, fix nothing until both have returned** — no acting on whichever finished first.
- **Merge, don't concatenate:** dedupe overlapping findings (same `path:line` / same issue), keep the higher severity, and tag each finding's source — `standard`, `adversarial`, or `both`. Adversarial-only findings are usually the subtle ones; don't drop them.
- Build one unified review: verdict line, a severity-ranked table (`Severity | path:line | source | one-liner`), the per-finding detail, and a "what's good" note when warranted.

### 5. Deliver the merged review (after both returned)

- **Always** print the merged review in chat — this is the guaranteed deliverable.
- **Posting is gated:** only if an **open** PR exists for the branch **and** the user consents.
  ```bash
  gh pr view <PR-or-branch> --json number,state,url --jq '{number,state,url}'
  ```
  No open PR (or closed/merged) → summary only, don't ask. If open, ask whether to post (show PR #/URL); default to not posting. On consent, post **comment-only** (never `--approve`/`--request-changes` unless asked), prefixing every comment with `Claude:3 `:
  ```bash
  gh api "repos/$OWNER/$REPO/pulls/<PR>/comments" -X POST \
    -f body="Claude:3 <severity> — <problem + fix direction>" \
    -f commit_id="$(gh pr view <PR> --json headRefOid --jq .headRefOid)" \
    -f path="<file>" -F line=<new-side line> -f side="RIGHT"
  gh pr review <PR> --comment --body "Claude:3 <verdict + severity table>"
  ```

### 6. Authoring mode — iterate, then re-invoke (skip in external mode)

- **External mode:** stop after step 5. Never edit someone else's code; never loop.
- **Authoring mode:** if the merged review has findings, fix them:
  1. Fix **root causes** — no workarounds, no disabling/skipping tests, no `--no-verify`.
  2. Add or adjust a test that **would have failed before** the fix, pinning the contract.
  3. Run the relevant test suite + lint; fix any breakage before continuing.
  4. **Re-invoke this skill from step 2** — a fresh two-reviewer pass on the updated code.
- Repeat until a cycle returns **no new findings** — that clean pass is "done".
- **Guardrails (mirroring `bugbot`):**
  - Print `Code-review cycle N` at the top of each pass so progress is visible.
  - **Cap: 5 cycles.** If still not clean after 5, stop and hand back with the current findings.
  - **Same finding twice in a row = stop and ask** — the fix isn't fixing it; don't churn variations.

## Rules

- **Reviewing happens in subagents, never the main agent.** Exactly two, dispatched in one turn so they run in parallel: standard + adversarial.
- **Both reviewers run on gpt-5.5(high)** (`model_override: openai/gpt-5.5`, which defaults to `high`). If a subagent can't be routed to that model, stop and say so — don't review on the default model.
- **No feedback before both return.** Don't deliver, post, or start fixing until both subagents are terminal. No partial reviews.
- **Merge, don't staple.** Dedupe, keep the higher severity, keep adversarial-only findings, tag sources.
- **Mode gates iteration.** Authoring → fix + re-invoke until clean. External → read-only, deliver only, never touch their code.
- **Posting needs an open PR + explicit consent.** Comment-only, `Claude:3 ` prefix. No open PR → summary only.
- **Fix root causes; tests gate every cycle.** Cap 5 cycles; same finding twice → stop and ask.
- **Ground every finding in code** (`path:line`); mark unverifiable downstream effects "unverified". Severity is your honest read — don't inflate nits or hedge a real blocker.

## Quick reference

| Phase | Who / model | Output |
|-------|-------------|--------|
| Identify + gather (1–2) | main agent / any model | context bundle + mode |
| Review (3) | **2 subagents / gpt-5.5(high)** | two finding sets, in parallel |
| Wait + merge (4) | main agent | one severity-ranked review |
| Deliver (5) | main agent | chat summary always; post if open PR + consent |
| Iterate (6, authoring only) | main agent | fixes + re-invoke until clean (cap 5) |

## Notes for the operator

- **Two reviewers, run together:** the adversarial pass catches what the balanced pass rationalizes away. Running them concurrently (not one after the other) keeps it fast and keeps the merge honest.
- **Wait-for-both** exists so you never act on half a review — a blocker from the slower reviewer shouldn't be missed because the other finished first.
- **The authoring loop re-invokes the whole skill**, so each cycle is a fresh, unbiased two-reviewer pass on the latest code. "No new findings" is then a real signal, not an agent rubber-stamping its own fix.
- **External mode is deliberately read-only** — reviewing someone else's PR never edits their branch.