Polytoken Reviewer Skill

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.

| --- | | | 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. |