{"slug": "polytoken-reviewer-skill", "title": "Polytoken Reviewer Skill", "summary": "A developer created a Polytoken Reviewer Skill that orchestrates two parallel reviewer subagents on gpt-5.5(high) for code review. The skill dispatches a standard reviewer and an adversarial reviewer concurrently, merges their findings, and delivers a single review. In authoring mode, the skill iterates by fixing findings and re-invoking until no issues remain.", "body_md": "| --- | |\n| name: code-review | |\n| 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. | |\n| disable-model-invocation: false | |\n| tags: | |\n| - productivity | |\n| polytoken: true | |\n| --- | |\n| # Code Review | |\n| 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. | |\n| 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. | |\n| > **Subagents + model — non-negotiable.** | |\n| > - 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. | |\n| > - 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`. | |\n| > - One is the **standard reviewer**, one is the **adversarial reviewer**. | |\n| > - The main agent only orchestrates: gather context → dispatch the two → wait for both → merge → deliver → (authoring mode) fix + re-invoke. | |\n| ## Modes — decide this first | |\n| - **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. | |\n| - **External mode** — *you're reviewing someone else's PR.* **Read-only**: deliver feedback, never edit their code, never iterate on their behalf. | |\n| If it's ambiguous who owns the changes, ask one clarifying question before reviewing. | |\n| ## The Loop | |\n| ``` | |\n| identify target + mode (authoring | external) | |\n| │ | |\n| ▼ | |\n| gather diff + context (main agent, any model) | |\n| │ | |\n| ▼ | |\n| dispatch TWO reviewer subagents in ONE turn — parallel, gpt-5.5(high): | |\n| • standard reviewer • adversarial reviewer | |\n| │ | |\n| ▼ | |\n| WAIT for BOTH to return ◄── deliver / post / fix NOTHING until both terminal | |\n| │ | |\n| ▼ | |\n| merge + dedupe findings → one severity-ranked review | |\n| │ | |\n| ▼ | |\n| deliver: in-chat summary (always) + post only if open PR & consent | |\n| │ | |\n| ┌────┴───────────────────────────────┐ | |\n| external mode authoring mode | |\n| │ │ | |\n| done findings? ──no──► clean — done | |\n| │ | |\n| yes → fix root cause + tests | |\n| │ | |\n| ▼ | |\n| RE-INVOKE this skill (fresh 2-reviewer pass) | |\n| until no new findings (cap 5 cycles) | |\n| ``` | |\n| ## Steps | |\n| ### 1. Identify the target and the mode | |\n| - **Target:** a PR number if the user gave one; otherwise the current branch vs. the repo's default base. | |\n| ``` bash | |\n| BASE=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) | |\n| OWNER=$(gh repo view --json owner --jq .owner.login) | |\n| REPO=$(gh repo view --json name --jq .name) | |\n| ``` | |\n| - **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: | |\n| ``` bash | |\n| gh pr view <PR> --json author,headRefName,state,url --jq '{author:.author.login,state,url}' | |\n| ``` | |\n| If ownership is unclear, ask one question. The mode decides whether step 6 runs. | |\n| ### 2. Gather the diff and context (main agent) | |\n| ``` bash | |\n| git fetch origin \"$BASE\" --quiet | |\n| git diff \"origin/$BASE...HEAD\" --name-only # changed files | |\n| git log \"origin/$BASE..HEAD\" --oneline # commits | |\n| git diff \"origin/$BASE...HEAD\" # full diff | |\n| gh pr view <PR> --json title,body,url,state,isDraft,baseRefName,headRefName # if a PR exists | |\n| ``` | |\n| 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. | |\n| ### 3. Dispatch the two reviewer subagents — parallel, gpt-5.5(high) | |\n| 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. | |\n| **Reviewer A — Standard.** A balanced, thorough review across, in priority order: | |\n| 1. Correctness & logic (does it do what the PR claims?) | |\n| 2. Edge cases & error handling | |\n| 3. Security (injection, authz/authn, secrets, unvalidated trust-boundary input) | |\n| 4. Concurrency (races, shared mutable state, cancellation) | |\n| 5. Performance & resource use (N+1s, unbounded growth, hot-path cost) | |\n| 6. API & compatibility (breaking signatures/schemas, migration safety) | |\n| 7. Tests (is the new behavior covered? tests that would fail before the change?) | |\n| 8. Readability & maintainability (nits, lowest priority) | |\n| Also call out **what's good**. | |\n| **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. | |\n| **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\". | |\n| ### 4. Wait for BOTH, then merge (main agent) | |\n| - 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. | |\n| - **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. | |\n| - 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. | |\n| ### 5. Deliver the merged review (after both returned) | |\n| - **Always** print the merged review in chat — this is the guaranteed deliverable. | |\n| - **Posting is gated:** only if an **open** PR exists for the branch **and** the user consents. | |\n| ``` bash | |\n| gh pr view <PR-or-branch> --json number,state,url --jq '{number,state,url}' | |\n| ``` | |\n| 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 `: | |\n| ``` bash | |\n| gh api \"repos/$OWNER/$REPO/pulls/<PR>/comments\" -X POST \\ | |\n| -f body=\"Claude:3 <severity> — <problem + fix direction>\" \\ | |\n| -f commit_id=\"$(gh pr view <PR> --json headRefOid --jq .headRefOid)\" \\ | |\n| -f path=\"<file>\" -F line=<new-side line> -f side=\"RIGHT\" | |\n| gh pr review <PR> --comment --body \"Claude:3 <verdict + severity table>\" | |\n| ``` | |\n| ### 6. Authoring mode — iterate, then re-invoke (skip in external mode) | |\n| - **External mode:** stop after step 5. Never edit someone else's code; never loop. | |\n| - **Authoring mode:** if the merged review has findings, fix them: | |\n| 1. Fix **root causes** — no workarounds, no disabling/skipping tests, no `--no-verify`. | |\n| 2. Add or adjust a test that **would have failed before** the fix, pinning the contract. | |\n| 3. Run the relevant test suite + lint; fix any breakage before continuing. | |\n| 4. **Re-invoke this skill from step 2** — a fresh two-reviewer pass on the updated code. | |\n| - Repeat until a cycle returns **no new findings** — that clean pass is \"done\". | |\n| - **Guardrails (mirroring `bugbot`):** | |\n| - Print `Code-review cycle N` at the top of each pass so progress is visible. | |\n| - **Cap: 5 cycles.** If still not clean after 5, stop and hand back with the current findings. | |\n| - **Same finding twice in a row = stop and ask** — the fix isn't fixing it; don't churn variations. | |\n| ## Rules | |\n| - **Reviewing happens in subagents, never the main agent.** Exactly two, dispatched in one turn so they run in parallel: standard + adversarial. | |\n| - **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. | |\n| - **No feedback before both return.** Don't deliver, post, or start fixing until both subagents are terminal. No partial reviews. | |\n| - **Merge, don't staple.** Dedupe, keep the higher severity, keep adversarial-only findings, tag sources. | |\n| - **Mode gates iteration.** Authoring → fix + re-invoke until clean. External → read-only, deliver only, never touch their code. | |\n| - **Posting needs an open PR + explicit consent.** Comment-only, `Claude:3 ` prefix. No open PR → summary only. | |\n| - **Fix root causes; tests gate every cycle.** Cap 5 cycles; same finding twice → stop and ask. | |\n| - **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. | |\n| ## Quick reference | |\n| | Phase | Who / model | Output | | |\n| |-------|-------------|--------| | |\n| | Identify + gather (1–2) | main agent / any model | context bundle + mode | | |\n| | Review (3) | **2 subagents / gpt-5.5(high)** | two finding sets, in parallel | | |\n| | Wait + merge (4) | main agent | one severity-ranked review | | |\n| | Deliver (5) | main agent | chat summary always; post if open PR + consent | | |\n| | Iterate (6, authoring only) | main agent | fixes + re-invoke until clean (cap 5) | | |\n| ## Notes for the operator | |\n| - **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. | |\n| - **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. | |\n| - **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. | |\n| - **External mode is deliberately read-only** — reviewing someone else's PR never edits their branch. |", "url": "https://wpnews.pro/news/polytoken-reviewer-skill", "canonical_source": "https://gist.github.com/haileyok/6be6e7b24bab608d509b659e07915ba8", "published_at": "2026-06-20 18:16:11+00:00", "updated_at": "2026-06-20 19:06:24.372761+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-agents"], "entities": ["Polytoken", "gpt-5.5", "Claude", "OpenAI"], "alternates": {"html": "https://wpnews.pro/news/polytoken-reviewer-skill", "markdown": "https://wpnews.pro/news/polytoken-reviewer-skill.md", "text": "https://wpnews.pro/news/polytoken-reviewer-skill.txt", "jsonld": "https://wpnews.pro/news/polytoken-reviewer-skill.jsonld"}}