Auto Review

Auto Review

Overview

Get a staff-engineer-grade review that's both broad (every dimension in parallel) and trustworthy (every finding survived a refutation attempt). The parallelism gives coverage; the adversarial gate gives signal — you get a short list of verified, severity-labeled, actionable findings instead of a long list you have to triage for hallucinations.

Inputs

• $scope: the diff/branch/PR or path to review (default: the current branch diff). Append the literal --fix to authorize resolving CONFIRMED blockers in place after the review.

Phase 0: Scope and baseline

• Resolve scope ($scope — the branch/PR diff by default; a path/module otherwise). Get the actual diff (git diff <base>...HEAD) and the changed files.
• Note the change size — an oversized diff (≫ a few hundred lines) is itself a finding (hard to review, should be split); say so.
• Open a checkpoint-resume run.

Success criteria: the exact diff + changed files are known; change-size noted.

Phase 1: Fan out the review dimensions

Launch one reviewer per dimension over the diff (fan-out-work), each an independent lens with the actual code in hand. (On Claude Code the dimensions run truly in parallel only at the ultracode effort level; with it off they run sequentially — same dimensions, same findings, just slower. If speed matters and it's off, mention /effort ultracode once, then proceed — never block the review on it.)

• correctness — logic errors, edge/error paths, off-by-one, null/empty, concurrency/races, wrong assumptions;
• security — trust boundaries, injection, authz, secrets, unsafe deserialization, untrusted input;
• performance — obvious hotspots, N+1s, needless allocations, blocking calls (measurement-gated claims — flag, don't assert a speedup);
• maintainability/readability — naming, structure, duplication, complexity, intent clarity;
• test adequacy — are the new behaviors covered by meaningful, non-vacuous tests? gaps?
• API/contract & compatibility — public interface changes, backward compatibility, error semantics, Hyrum's-Law surface.

Each reviewer returns structured findings (file:line, issue, severity, suggested fix, a concrete failure scenario).

Success criteria: every dimension ran (or its failure is recorded as a gap); raw findings collected.

Phase 2: Dedup + adversarially verify (the signal gate)

• Dedup the raw findings across dimensions (same file:line + same issue → one), keeping the highest severity and merging rationale.
• Verify each with adversarial-verify: skeptics get the real code and try to REFUTE the finding (does the bug actually occur? build the input; is the "vulnerability" reachable?). Scale skeptics to severity (a blocker gets a stronger panel). Only survivors are kept; refuted findings go to a rejection ledger (reported, so you see what was filtered).

Success criteria: a deduped list of VERIFIED findings, each severity-labeled; unverified (dead-panel) findings kept open; rejected findings logged.

Phase 3: Report — or, if asked, fix the blockers (bounded)

• Report (default): the verified findings by severity, each with file:line, why, and a suggested fix; plus coverage (which dimensions ran) and the rejection ledger. Fail closed — name any dimension that didn't run.
• Fix (only on --fix intent): run converge-loop over the CONFIRMED blockers/concerns — one minimal fix per finding, re-verify the finding is resolved and no regression introduced, until the confirmed set is clear or the loop bounds out. Nits/FYIs are not auto-fixed. Update the checkpoint per finding.

Success criteria: the user gets verified findings (and, if requested, the confirmed blockers resolved in place with no regressions); coverage and rejections are honest.

Common Rationalizations

Red Flags

• Findings reported without any verification step.
• A "clean" verdict where one or more dimensions silently didn't run.
• Severity inflation (nits as blockers) or burial (blockers as nits).
• Fixes applied for unconfirmed or nit-level findings, or bundled with unrelated refactors.
• A huge diff reviewed without noting it should be split.
• The rejection ledger hidden (you can't see what was filtered and why).

Guardrails

• Never report or fix an unverified finding — adversarial-verify first.
• Never treat a non-running dimension as clean; fail closed and name the gap.
• Never inflate/bury severity; label honestly.
• Never auto-fix beyond confirmed blockers/concerns; keep fixes minimal and re-verified.
• Never fabricate an approving verdict over surviving findings.

When To Load References

• references/review-workflow.js — the RUNNABLE Workflow for Phases 1–2: one reviewer per dimension → dedup (a genuine barrier) → majority-refute skeptic panel per finding → returns { clean, confirmed, unverified, rejected, coverage } — fail-closed on any dimension that didn't run AND on any skeptic panel that died below quorum (those findings come back unverified, kept open, never dropped). Launch via the Workflow tool with { root, diffCmd }; prefer it over hand-orchestrating the fan-out.
• fan-out-work (skill) — parallel per-dimension review over the diff.
• adversarial-verify (skill) — the per-finding refutation gate (Phase 2) — the core signal mechanism.
• converge-loop (skill) — the optional bounded fix loop for confirmed blockers.
• checkpoint-resume (skill) — durable review/fix state.

Output Contract

Report:

1. scope + diff size (flag if it should be split); dimensions that ran (coverage — fail closed on gaps)
2. verified findings by severity (Blocker / Concern / Nit / FYI): file:line, issue, failure scenario, suggested fix
3. unverified findings — where the skeptic panel died below quorum (fail closed: kept OPEN as needing re-verification or hand review, never dropped or counted clean) — matches the workflow's unverified return
4. rejection ledger — findings refuted by verification (so filtering is visible)
5. if --fix: confirmed blockers resolved (each re-verified, no regressions) vs. left for the user