agent-review-panel

name

agent-review-panel

description

Orchestrate a multi-agent adversarial review panel where several Claude Code subagents with different perspectives independently review a piece of work, debate with each other, reach (or fail to reach) consensus, then a supreme judge renders the final verdict. Use this skill whenever the user asks for a "review panel", "multi-agent review", "adversarial review", "have agents debate this", "review with multiple perspectives", "panel review", "get different opinions on this code/plan/doc", or invokes /agent-review-panel. Also trigger when a user says things like "I want thorough feedback from different angles", "stress-test this design", "red team this", "get a second (third, fourth) opinion", "fresh eyes on this", "multiple reviewers", "devil's advocate perspective", "every angle covered", "I want agents to argue pros and cons", "independently evaluate", "critical look from security and performance angles", "high-stakes — cover every angle", or "debate the pros and cons". This skill is specifically about launching multiple reviewer agents with distinct personas who discuss and debate — NOT for single-reviewer code review, quick sanity checks, bug fixes, deployment tasks, addressing existing PR comments, skill improvement, peer review, code explanation, or writing tests. Supports "deep research mode" when user says "deep review", "thorough review", "research review", or passes "deep" to /agent-review-panel — adds web research for domain best practices before launching reviewers. Supports "multi-run union mode" when user says "multi-run review", "run N times and merge", "run twice", "run 3 times", or "maximum coverage review" — repeats the panel with rotated persona sets and merges results with stability scoring. Supports "data flow trace tiers" (Standard/Thorough/Exhaustive) when user says "thorough review", "exhaustive review", "trace everything", or "catch all bugs" — dedicates a pre-review phase to tracing data through critical paths and flagging composition/seam bugs. Supports "budget mode" when user says "budget review", "budget mode", "budget panel", "cheap review", "economy review", "low-cost panel", "affordable review", "token-efficient review", "frugal review", "lite panel", or passes "budget" to /agent-review-panel — and ALSO when any panel request carries a cost constraint, e.g. "review panel but keep the cost down", "multi-agent review without burning tokens", "panel review but don't spend too much", "review this cheaply with multiple perspectives", "watch the token spend". Budget mode is the same adversarial protocol at a reduced-cost profile (3 sonnet reviewers, single debate round, consolidated verification, opus judge, markdown-only output).

Agent Review Panel v3.8.0

A multi-agent adversarial review system based on nine research foundations: ChatEval (ICLR 2024), AutoGen, Du et al. (ICML 2024), MachineSoM (ACL 2024), DebateLLM, DMAD (ICLR 2025), "Talk Isn't Always Cheap" (ICML 2025), CONSENSAGENT (ACL 2025), Trust or Escalate (ICLR 2025 Oral).

When NOT to Use This Skill

Do NOT trigger for these requests — they need single-agent handling or other skills:

• Single code review ("review this function for bugs")
• Quick sanity checks ("just a quick look before I push")
• Bug fixes ("fix the type errors", "fix the failing test")
• Peer review without multi-perspective signal ("peer review this doc")
• Code explanation ("what does this code do?")
• Deployment tasks ("deploy to staging")
• Addressing existing feedback ("address the PR comments")
• Skill improvement ("make this skill better") → use schliff
• Writing tests, READMEs, or documentation
• Asking for a single opinion ("what do you think?", "is this any good?")

The key signal is multiple independent perspectives — if the user wants one opinion, don't launch a panel.

Input

This skill takes as input one or more of: file paths to review, inline code/text in the conversation, a git diff or PR reference, or a plan/design document. It expects the user to specify (or let it auto-detect) what to review.

Dependencies

This skill depends on the Agent tool to launch parallel subagent reviewers and requires bash for context gathering (grep, file reads). Every agent launch MUST pass a model: parameter explicitly — never rely on defaults. In the full panel that model is model: "opus" for every agent. In budget mode (v3.7.0, see Budget Mode section) reviewers and the consolidated verifier use model: "sonnet" while the Supreme Judge stays on model: "opus" — the explicit-model rule is unchanged; only the chosen tier differs. This includes VoltAgent specialist agents launched via subagent_type — always pass the model explicitly alongside subagent_type to override the agent's default. Omitting it causes the launched agent to fall through to its own frontmatter-declared model (which may be sonnet or haiku), introducing cross-run reasoning variance. Knowledge mining reads from memory paths if they exist; if not available, it degrades gracefully — no hard dependency.

HTML report CDN dependencies (Phase 15.3 output file only): The generated review_panel_report.html loads Tailwind CSS, Chart.js, and — new in v2.15 — Prism.js from CDN for syntax highlighting in the Code Evidence sections of expandable issue cards. If the CDNs are unreachable, the HTML degrades gracefully: layout and text remain readable, charts show a placeholder, code blocks render as unstyled monospace.

Optional enhancement: When VoltAgent specialist agents are installed, the panel can use them instead of generic persona-prompted agents for stronger domain-specific reviews. See "VoltAgent Integration" section below.

This skill is scoped to multi-perspective adversarial review. For skill improvement requests, use schliff instead. For post-review plan updates, use plan-review-integrator. Supported versions: Claude Code v1.0+.

Examples

Example 1: Code review panel Input: "Do a review panel on src/auth/middleware.ts — I want multiple perspectives before merging" Output: Classifies as pure code → selects Correctness Hawk + Architecture Critic + Security Auditor + Devil's Advocate → gathers context → 4 parallel reviewers → 2 debate rounds → completeness audit → claim verification → supreme judge → writes review_panel_report.md

Example 2: Mixed content with deep research Input: "Deep review of our migration plan — it includes SQL and Terraform" Output: Classifies as mixed → adds Code Quality Auditor + Data Quality Auditor (SQL signal) + Reliability/SRE (infra signal) → runs web research for best practices → full panel → report with epistemic labels

Process Overview

Phase 1:    Setup                     → Identify work, pick personas, define criteria
Phase 2:    Data Flow Trace           → Trace critical path(s), document schemas [code only] (v2.14)
Phase 3:    Independent Review        → All reviewers evaluate in parallel (no cross-talk)
Phase 4:    Private Reflection        → Each reviewer re-reads source, rates own confidence
Phase 5:    Debate (rounds 1–3)       → Reviewers engage with each other + find new issues
Phase 6:    Round Summarization       → Distill resolved/unresolved points between rounds
Phase 7:    Blind Final               → Each reviewer gives final score independently
Phase 8:    Completeness Audit        → Dedicated agent scans for what the panel missed
Phase 9:    Verify Commands           → Run up to 5 reviewer verification commands (advisory)
Phase 10:   Claim Verification        → Verify all line-number citations against source
Phase 11:   Severity Verification     → Read actual code for every P0/P1, downgrade if overstated + web-verify external domain claims (v2.16.3)
Phase 12:   Verification Tier Assign  → Confidence draft (12a) + judge-advised refinement (12b)
Phase 13:   Targeted Verification     → Persona-matched agents dispatched per dispute point
Phase 14:   Supreme Judge             → Opus arbitrates everything including verification round
Phase 14.5: Post-Judge Verification   → Re-verify judge-introduced P0/P1 against ground truth (v3.2.0)
Phase 15:   Output Generation         → (parent) Three output files (all sequential: 15.1 → 15.2 → 15.3)
  Phase 15.1: Primary Markdown Report → Structured markdown summary (review_panel_report.md)
  Phase 15.2: Process History         → Full director's-cut log (review_panel_process.md)
  Phase 15.3: HTML Report             → Interactive dashboard (review_panel_report.html)

[Multi-Run mode (--runs N > 1): repeat Phases 2–15 with rotated personas, then:]
Phase 16:   Merge                     → Deduplicate, score stability, produce merged report (v2.14)

[Budget mode ("budget review", v3.7.0): same protocol shape at a reduced-cost
profile — 3 sonnet reviewers, Phases 3+4 merged, exactly 1 debate round,
Phases 8+10+11 as ONE consolidated verification agent, no 12b/13, opus judge,
14.5 as an orchestrator grep-check, Phase 15.1 markdown output only.
See the Budget Mode section.]

---

Phase 1: Setup

Identify the Work

The user provides: file paths, inline content, git diff/PR, or a plan/design doc. Collect full content, then run Context Gathering (below).

Classify content type (matters for persona selection):

• Pure code — only code files
• Pure plan/design — architecture docs, proposals, RFCs
• Mixed — plans with code snippets, SQL, or config
• Documentation — READMEs, guides, API docs

Review Mode Detection (v2.8)

Auto-detect review mode from content type. No user toggle.

Content Type	Review Mode	Behavior
Pure code	Precise	Every finding MUST cite a specific file, line number, or code snippet. Findings without concrete evidence are demoted to [UNVERIFIED].
Pure plan/design	Exhaustive	Broader risk identification allowed. Findings may reference design sections or architectural patterns without line-number evidence.
Mixed	Precise for code, Exhaustive for prose	Reviewers label each finding with its mode. Code findings without line citations are demoted.
Documentation	Exhaustive	Same as plan/design.
Subjective-quality deliverable (strategy report, marketing/creative copy, pitch deck, research synthesis)	Assessment	Goal is quality discrimination, not defect-finding. Score each axis 0–10 by subtract-points + veto, run the swap test, fact-check currency out-of-band, and control-validate the personas against a known-bad floor. See Assessment Mode below.

The detected mode is injected into Phase 3 reviewer prompts and the judge prompt. Report header states the detected mode.

Detect Content Signals

Scan work for technology-specific signals (case-insensitive, 3+ keyword threshold). See references/signals-and-checklists.md for the full detection table and domain checklists. Signal detection only fires when auto-selecting personas.

Context Gathering

Run these steps before launching reviewers for file-path reviews. Skipping is the #1 cause of incorrect [CRITICAL] recommendations.

1. Sibling Directory Scan — From reviewed files' parent, scan for docs/, README*, CLAUDE.md, config.py, package.json, etc. Read first 50 lines of each. If files are nested, scan both immediate parent and project root.

2. Reference Tracing — Scan for imports, config references, cross-file references in comments, SQL table references, file path strings.

3. Safety Mechanism Discovery — Grep reviewed code + imports for: _valid, _flag, _guard, _check, _mask, <= target_date, BETWEEN, fillna, COALESCE, try/except, DELETE FROM, MERGE, WRITE_TRUNCATE, upsert, idempoten, --dry-run, duplicate, assertion. Note what each guards against. Critical: When a finding claims "X is missing", verify the claim by grepping the actual code — existing safety mechanisms are the #1 thing panels miss (v2.6 benchmark: panel claimed "non-idempotent writes" but DELETE-then-INSERT with duplicate validation already existed).

3b. Temporal Scope Verification — When the work contains ANY temporal claims (e.g., "excludes Christmas", "masks winter period", "filters out weekends", "pre-period starts after X"), verify that the exclusion applies to ALL instances across the full date range, not just the first/most-obvious one. Common failure: "excludes Christmas" via a Jan 6 start date only excludes the first Christmas — a second Christmas 12 months later may still be in the training window. This class of bug evaded 3 rounds of adversarial review (12 reviewers) in a real engagement — the user caught it 6 days later. Inject into reviewer prompts: "For any temporal exclusion claim, count how many instances of the excluded event exist in the date range and verify ALL are excluded, not just one."

3c. Codebase State Check (v2.10) — When reviewing code that lives in a git repository, determine the exact codebase state being reviewed. This prevents the panel from flagging code as "missing" when it exists on main but not in the reviewed branch/worktree.

Why this matters: In a real engagement, a 4-reviewer panel + completeness auditor unanimously flagged a class as "non-existent" — but it existed on main (merged via a PR after the worktree branched). All reviewers checked the worktree files, none checked main. The finding was confidently wrong.

Steps:

# 1. Detect if we're in a worktree
git rev-parse --is-inside-work-tree 2>/dev/null && \
WORKTREE=$(git rev-parse --show-toplevel) && \
BRANCH=$(git rev-parse --abbrev-ref HEAD)

# 2. Find the default branch (main or master)
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@') || DEFAULT_BRANCH="main"

# 3. Find the branch point and count divergence
MERGE_BASE=$(git merge-base HEAD origin/$DEFAULT_BRANCH 2>/dev/null)
COMMITS_BEHIND=$(git rev-list --count HEAD..origin/$DEFAULT_BRANCH 2>/dev/null || echo "unknown")

# 4. List PRs/commits merged to main since branch point
git log --oneline $MERGE_BASE..origin/$DEFAULT_BRANCH 2>/dev/null | head -20

If commits_behind > 0: Include a [STALE_BRANCH] warning in the context brief listing what was merged to main since the branch point. Inject into ALL reviewer prompts: "The code under review is {N} commits behind {default_branch}. These changes were merged since: {list}. Before claiming code or features are 'missing', check whether they exist on {default_branch} via git show {default_branch}:{filepath}."

If in a git worktree specifically (detected via git worktree list): add extra emphasis — worktrees are commonly used for isolated development and are especially prone to divergence from main.

Record in Context Brief: Add a "Codebase State" section with: branch name, commits behind main, key PRs merged since branch point, worktree status.

4. Knowledge Mining (tiered loading) — Mine local knowledge using a 3-tier approach to minimize token waste while maximizing relevant context:

   L0 — Index scan (~100 tokens each). Read only index lines and frontmatter description fields. Filter for relevance to the work under review.

   • MEMORY.md — read index lines only (each ~150 chars). Match keywords from the work's content type, domain, and technology signals.
   • ~/.claude/skills/*/SKILL.md — read only the YAML description: field (glob + grep for ^description:). Match against detected content signals.
   • CLAUDE.md — always load (small, high-authority).

   L1 — Summary scan (~500 tokens each). For L0-matched items only, read frontmatter + first paragraph to confirm relevance.

   • Memory files (feedback_*.md, project_*.md) — read first 20 lines. feedback_*.md files matching the review domain get automatic L2 promotion (past corrections are HIGHEST PRIORITY).
   • Skill files — read the description: + ## When NOT to Use section.
   • lessons.md — scan for lines matching review domain keywords.

   L2 — Full content (no limit). Only for confirmed-relevant items from L1.

   • Read the complete file for items that passed L1 relevance check.
   • Typical yield: 3-8 files at L2 out of 50+ candidates at L0.

   Deduplication: if the same insight appears in multiple sources, include only the most specific version (project > global > skill).

5. Web Research (deep research mode only) — Triggers when user requests "deep review" or 5+ keywords from a signal group with no built-in checklist. Cap at 2 web searches. Tag findings with [WEB]. If the built-in domain checklist already covers the signal group, web research is skipped unless explicitly requested.

6. Context Brief — Compile into structured brief with sections: Codebase State, System Documentation Found, Referenced Files, Safety Mechanisms, Knowledge Mining Results, Web Research Findings, Domain Checklist, Context Gaps.

7. User Confirmation — If significant context gaps exist or deep research is available but not requested, ask before proceeding.

Select Personas with Agreement Intensity

If user specifies personas, use those. Otherwise select 4 from content-type sets:

For code/implementation:

1. Correctness Hawk (30%) — Bugs, logic errors, edge cases
2. Architecture Critic (50%) — Design patterns, coupling, extensibility
3. Security Auditor (30%) — Vulnerabilities, injection, auth gaps
4. Devil's Advocate (20%) — Challenges everything, proposes alternatives

For plans/designs (pure — no code):

1. Feasibility Analyst (60%) — Technical feasibility, timeline realism
2. Stakeholder Advocate (50%) — Business perspective, ROI
3. Risk Assessor (30%) — Failure modes, dependencies
4. Devil's Advocate (20%)

For mixed content (plans WITH code/SQL/config) — CRITICAL:

1. Feasibility Analyst (60%)
2. Code Quality Auditor (40%) — Line-by-line scrutiny of every snippet
3. Risk Assessor (30%)
4. Devil's Advocate (20%)

For documentation:

1. Clarity Editor (60%)
2. Technical Accuracy Reviewer (30%)
3. Completeness Checker (40%)
4. Devil's Advocate (20%)
5. Fresh-Reader Reviewer (50%) — reads the doc COLD as a newcomer with zero prior context: catches journey-narration ("now built", "corrected this round", dated probes, "was X — now Y", "superseded"), assumed prior knowledge / undefined jargon / internal nicknames, and feasibility-vs-built identity confusion — defects Clarity/Accuracy/Completeness routinely miss. Strongly recommended (replace Devil's Advocate) for any near-final delivery / feasibility / status / handoff document, especially one heavily iterated or mass-rewritten. Dispatch via the Fresh-Reader Delivery Reviewer agent.

For subjective-quality deliverables (Assessment mode — strategy / marketing / creative / research output): GENERATE 4 domain-tailored adversarial personas (do not reuse the generic sets — saturation comes from generic "is this good?" questions). Each must ask a question that exposes a difference a generic reviewer misses, and all four default to HIGH agreement-intensity (appreciative personas re-saturate):

1. Domain-Authenticity Critic (90%) — "does this ring true to a real practitioner/native of this space, or is it a plausible outsider's caricature?"
2. Executability / Operator (90%) — "could I act on this tomorrow? name the concrete next step, number, or channel — any vagueness = a castle in the air."
3. Decision-Maker / ROI (90%) — "would I fund or ship this? what's the measurable commitment, and is the claimed upside real or just baseline?"
4. Intent-Fidelity Critic (90%) — "does this serve the specific brief/brand/audience — or would it read identically for a competitor? (apply the swap test in Assessment Mode.)" Tailor each archetype's wording to the deliverable's actual domain. Worked example — a China beauty-brand strategy report: 化妆品合规审查员 (regulatory, with veto) · 本土电商操盘手 (executability) · 比稿甲方 / ROI 审计官 (decision-maker) · 成分党品牌死忠 (intent fidelity). Reasoning strategies: adversarial simulation + first-principles.

After base selection, auto-add signal-detected personas (up to 6 total). Replace Devil's Advocate first if at cap (keep ≥1 DA if panel ≥4).

CRITICAL: If work contains ANY code/SQL/config snippets, always include Code Quality Auditor — the #1 cause of missed details in v1.

Reasoning Strategy Assignment (DMAD, ICLR 2025)

Persona Type	Strategy	Injection
Correctness Hawk / Code Quality Auditor	Systematic enumeration	"Enumerate every code path, constant, edge case."
Architecture Critic / Feasibility Analyst	Backward reasoning	"Start from desired outcome, trace backward."
Security Auditor / Risk Assessor	Adversarial simulation	"Imagine you are an attacker. How would you break this?"
Devil's Advocate	Analogical reasoning	"Compare to known failure patterns from similar projects."
Stakeholder Advocate / Clarity Editor	First-principles	"Question every assumption from scratch."
Fresh-Reader Reviewer	Cold first-read	"You have zero prior context. Read as a newcomer; flag anything that narrates the team's journey, assumes prior knowledge, or leaves the doc self-contradictory."
Auto-added specialists	Checklist verification	"Use your domain checklist. Verify each item."

Default Evaluation Criteria

Correctness, Completeness, Quality, Edge Cases (override if user specifies). (Assessment mode overrides these — see below.)

Assessment Mode (v3.6) — quality discrimination, not defect-finding

Triggers when the work is a subjective-quality deliverable (a strategy report, marketing/creative copy, a pitch, a research synthesis) rather than code/plan/docs. The other modes hunt discrete defects; here the failure mode is saturation — every competent draft reads good, so a generic "rate 0–10" panel hands out 8–9s to everything, including a confident-but-empty draft. The job is to discriminate quality, which needs different machinery:

1. Subtract-points + veto (not add-points). Start each axis at 10; adversarial personas deduct 1–2 per hole, cliché, or unsupported claim. A fatal domain violation (regulatory red-line, factually impossible claim) is a veto → 0 on that axis, not averaged away. Add-points scoring produces agreeable 9s; subtract-points forces "good" to mean "survived the deductions."

2. The swap test (cheap specificity probe). Replace the subject's proper noun (brand/product/person) with a plausible competitor's. If the deliverable still reads as true, it has zero specificity — flag it. Automatable; directly attacks "generic draft scores high."

3. Out-of-band fact-check for currency. A persona cannot tell a confident current fact from a confident stale one — it has no ground truth. So any freshness / factual / quantitative claim (market sizes, prices, dates, "latest X") must be verified against a curated checklist built from primary sources outside the panel and scored deterministically. Never let a persona "rate freshness." See skill llm-judge-cant-detect-stale-or-fabricated-grounding.

4. THE CONTROL-VALIDATION GATE — the signature step. Before trusting any Assessment score, calibrate the panel: construct a degenerate control — a version of the deliverable made with NO real input (generic template / no research / subject name find-replaced) — and run it through the SAME personas. A persona is valid only if it scores the control clearly below the real deliverable (rule of thumb: control < 3/10). A persona that rates the degenerate control as highly as the real one is non-discriminating sycophancy → drop it and report it. This is the assessment analogue of the Phase 6 CONSENSAGENT sycophancy check, but it tests the panel against a known-bad floor rather than against reviewer agreement — run it whenever scores look suspiciously uniform, in ANY mode.

Assessment criteria (override the defaults): Insight (a falsifiable, non-obvious claim — not rhetoric like "counter-intuitive"), Specificity (survives the swap test), Executability, Domain-authenticity, plus an out-of-band Currency axis. Demote/merge generic "completeness" (rewards padding) and "readability" (everyone writes pretty) — they're the weakest discriminators.

Report: state mode = Assessment; per-axis scores with the deductions that produced them; swap-test result; out-of-band currency verdict; and the control-validation result (which personas passed / were dropped). If no control was run, cap confidence at Medium and say so.

Worked example (monksIQ China brand-report bake-off, 2026-06): a 6-judge panel's four generic quality axes all saturated at 8–9.5 — a no-data control scored as high as real reports — and only an out-of-band freshness checklist plus adversarial domain personas (compliance-with-veto / e-commerce-operator / pitch-ROI / brand-fidelity) discriminated. Asked to design their own panel, the strongest models independently proposed subtract-points, the swap test, and this control-validation gate.

VoltAgent Integration (v2.9)

VoltAgent specialist agents (130+ across 10 families) have built-in domain expertise via their system prompts, making them stronger reviewers than generic persona-prompted agents. When available, the panel should upgrade personas to VoltAgent agents. Full catalog: github.com/VoltAgent/awesome-claude-code-subagents (a point-in-time snapshot of every agent the mapping tables below may reference is vendored at references/voltagent-catalog.json; run scripts/refresh-voltagent-catalog.sh to regenerate it and scripts/voltagent-catalog-check.sh to detect drift).

Step 1: Check availability. During Phase 1 setup, check whether VoltAgent agents are available by scanning the system-reminder agent list for any voltagent-* prefixed agents. Note which families are installed.

Step 2: Map personas to specialists. Use this mapping table. (When launching any persona via subagent_type, ALWAYS pass model: "opus". v2.14.)

Core Persona Mapping (review panel built-in personas)

Persona	Primary VoltAgent	Alt VoltAgent	Fallback
Correctness Hawk	voltagent-qa-sec:code-reviewer	voltagent-qa-sec:debugger	Generic + prompt
Architecture Critic	voltagent-qa-sec:architect-reviewer	voltagent-infra:cloud-architect	Generic + prompt
Security Auditor	voltagent-qa-sec:security-auditor	voltagent-qa-sec:penetration-tester	Generic + prompt
Code Quality Auditor	voltagent-qa-sec:code-reviewer		Generic + prompt
Feasibility Analyst	voltagent-data-ai:data-scientist	voltagent-biz:business-analyst	Generic + prompt
Risk Assessor	voltagent-qa-sec:chaos-engineer	voltagent-domains:risk-manager	Generic + prompt
Performance Specialist	voltagent-qa-sec:performance-engineer	voltagent-infra:sre-engineer	Generic + prompt
Stakeholder Advocate	voltagent-biz:product-manager	voltagent-biz:business-analyst	Generic + prompt
Devil's Advocate	Generic + prompt		(intentionally generic)
Data Quality Auditor	voltagent-data-ai:data-analyst	voltagent-data-ai:data-engineer	Generic + prompt
Reliability/SRE	voltagent-infra:sre-engineer	voltagent-infra:devops-incident-responder	Generic + prompt
DevOps/Infra	voltagent-infra:devops-engineer	voltagent-infra:platform-engineer	Generic + prompt
Database Specialist	voltagent-data-ai:database-optimizer	voltagent-data-ai:postgres-pro	Generic + prompt
Clarity Editor	voltagent-dev-exp:documentation-engineer	voltagent-biz:technical-writer	Generic + prompt
Technical Accuracy	voltagent-qa-sec:code-reviewer		Generic + prompt
Completeness Checker	voltagent-qa-sec:qa-expert		Generic + prompt
Fresh-Reader Reviewer	Fresh-Reader Delivery Reviewer (custom cold-read agent)		Generic + prompt

Signal-Detected Specialist Mapping (auto-added by content signals)

When content signals trigger auto-addition of specialist reviewers, use these VoltAgent agents instead of generic personas:

Content Signal	Auto-Add Persona	VoltAgent subagent_type
Delivery / feasibility / status / handoff doc (esp. heavily iterated or mass-rewritten)	Fresh-Reader Reviewer	Fresh-Reader Delivery Reviewer
SQL / database queries	Data Quality Auditor	voltagent-data-ai:database-optimizer
Terraform / IaC	Infrastructure Reviewer	voltagent-infra:terraform-engineer
Terragrunt	Infrastructure Reviewer	voltagent-infra:terragrunt-expert
Docker / containers	Container Reviewer	voltagent-infra:docker-expert
Kubernetes / k8s	K8s Reviewer	voltagent-infra:kubernetes-specialist
CI/CD / pipelines	Pipeline Reviewer	voltagent-infra:deployment-engineer
ML / model training	ML Reviewer	voltagent-data-ai:ml-engineer
LLM / prompts	LLM Reviewer	voltagent-data-ai:llm-architect
NLP / text processing	NLP Reviewer	voltagent-data-ai:nlp-engineer
React / frontend	Frontend Reviewer	voltagent-lang:react-specialist
TypeScript	TS Reviewer	voltagent-lang:typescript-pro
Python	Python Reviewer	voltagent-lang:python-pro
Go / Golang	Go Reviewer	voltagent-lang:golang-pro
Rust	Rust Reviewer	voltagent-lang:rust-engineer
Java / Spring	Java Reviewer	voltagent-lang:java-architect
.NET / C#	.NET Reviewer	voltagent-lang:csharp-developer
Ruby / Rails	Rails Reviewer	voltagent-lang:rails-expert
PHP / Laravel	PHP Reviewer	voltagent-lang:laravel-specialist
Swift / iOS	iOS Reviewer	voltagent-lang:swift-expert
Flutter / Dart	Flutter Reviewer	voltagent-lang:flutter-expert
GraphQL	GraphQL Reviewer	voltagent-core-dev:graphql-architect
WebSocket / real-time	Real-time Reviewer	voltagent-core-dev:websocket-engineer
Microservices	Architecture Reviewer	voltagent-core-dev:microservices-architect
API design	API Reviewer	voltagent-core-dev:api-designer
Network / DNS / routing	Network Reviewer	voltagent-infra:network-engineer
Azure	Azure Reviewer	voltagent-infra:azure-infra-engineer
Active Directory	AD Security Reviewer	voltagent-qa-sec:ad-security-reviewer
PowerShell	PowerShell Reviewer	voltagent-qa-sec:powershell-security-hardening
Compliance / GDPR / SOC2	Compliance Reviewer	voltagent-qa-sec:compliance-auditor
Accessibility / a11y	Accessibility Reviewer	voltagent-qa-sec:accessibility-tester
Error handling / logging	Error Reviewer	voltagent-qa-sec:error-detective
Test automation	Test Reviewer	voltagent-qa-sec:test-automator
Blockchain / Web3	Blockchain Reviewer	voltagent-domains:blockchain-developer
Payment / fintech	Fintech Reviewer	voltagent-domains:fintech-engineer
IoT / embedded	Embedded Reviewer	voltagent-domains:embedded-systems
SEO	SEO Reviewer	voltagent-domains:seo-specialist
Quant / financial models	Quant Reviewer	voltagent-domains:quant-analyst
Vue / Nuxt	Vue Reviewer	voltagent-lang:vue-expert
Angular	Angular Reviewer	voltagent-lang:angular-architect
Next.js	Next.js Reviewer	voltagent-lang:nextjs-developer
React Native / Expo	Mobile Reviewer	voltagent-lang:expo-react-native-expert
Electron / desktop apps	Desktop Reviewer	voltagent-core-dev:electron-pro
Django	Django Reviewer	voltagent-lang:django-developer
FastAPI	FastAPI Reviewer	voltagent-lang:fastapi-developer
Spring Boot	Spring Boot Reviewer	voltagent-lang:spring-boot-engineer
Symfony	Symfony Reviewer	voltagent-lang:symfony-specialist
C / C++	C++ Reviewer	voltagent-lang:cpp-pro
Kotlin	Kotlin Reviewer	voltagent-lang:kotlin-specialist
Elixir / Phoenix	Elixir Reviewer	voltagent-lang:elixir-expert
MLOps / model deployment	MLOps Reviewer	voltagent-data-ai:mlops-engineer
Reinforcement learning	RL Reviewer	voltagent-data-ai:reinforcement-learning-engineer
Prompt optimization / evals	Prompt Reviewer	voltagent-data-ai:prompt-engineer
AI systems / agentic apps	AI Systems Reviewer	voltagent-data-ai:ai-engineer
Database admin / replication / HA	DBA Reviewer	voltagent-infra:database-administrator
Incident response / outages	Incident Reviewer	voltagent-infra:incident-responder
Windows Server / IIS	Windows Reviewer	voltagent-infra:windows-infra-admin
Cloud security / secrets mgmt	Cloud Security Reviewer	voltagent-infra:security-engineer
CLI tools / TUIs	CLI Reviewer	voltagent-dev-exp:cli-developer
MCP servers / tools	MCP Reviewer	voltagent-dev-exp:mcp-developer
Refactoring / legacy modernization	Refactoring Reviewer	voltagent-dev-exp:refactoring-specialist
Build systems / bundlers	Build Reviewer	voltagent-dev-exp:build-engineer
Dependencies / supply chain	Dependency Reviewer	voltagent-dev-exp:dependency-manager
Git workflows / branching	Git Workflow Reviewer	voltagent-dev-exp:git-workflow-manager
Game dev / engines	Game Reviewer	voltagent-domains:game-developer
API docs / OpenAPI	API Docs Reviewer	voltagent-domains:api-documenter
Legal / licensing / contracts	Legal Reviewer	voltagent-biz:legal-advisor
UX research / usability	UX Research Reviewer	voltagent-biz:ux-researcher

Multi-Agent Orchestration Mapping (for pre/post-panel phases)

All launches below MUST pass model: "opus" explicitly (v2.14).

Review Phase	VoltAgent subagent_type	Use When
Data Flow Trace (Phase 2)	voltagent-data-ai:data-engineer, model: "opus"	Trace data paths, document schemas at boundaries (v2.14)
Completeness Audit (Phase 8)	voltagent-meta:knowledge-synthesizer, model: "opus"	Synthesize what the panel missed
Claim Verification (Phase 10)	voltagent-qa-sec:code-reviewer, model: "opus"	Verify line-number citations
Severity Verification (Phase 11)	voltagent-qa-sec:debugger, model: "opus"	Read actual code for P0/P1 findings
Tier Refinement Advisor (Phase 12b)	Generic, model: "opus"	(must be domain-neutral to refine tiers)
Verification Agents (Phase 13)	Persona-matched — see Phase 13 table, model: "opus"	Each agent matched to claim type
Supreme Judge (Phase 14)	Generic, model: "opus"	(judge must be domain-neutral)
Judge-Output Verifier (Phase 14.5)	Generic, model: "opus"	Re-verifies judge-introduced P0/P1 against ground truth via grep/Read/git (v3.2.0)
HTML Report Agent (Phase 15.3)	voltagent-lang:javascript-pro, model: "opus"	Generate interactive HTML dashboard with expandable issue cards (v2.15). Reads from disk: Phase 15.1 report + Phase 15.2 process history + rendering spec from prompt-templates.md (v2.16.4). Loads Tailwind, Chart.js, and Prism.js via CDN.
Merge Agent (Phase 16)	voltagent-meta:knowledge-synthesizer, model: "opus"	Deduplicate + score stability in multi-run mode (v2.14)

Step 3: Suggest installation when beneficial. If a selected persona would benefit from a VoltAgent agent but the agent family is not available, suggest installation to the user:

"This review would benefit from VoltAgent specialist agents for deeper domain-specific analysis. You can install the relevant families with:

Quick install (CLI): claude plugin install voltagent-qa-sec — security, code review, testing claude plugin install voltagent-data-ai — data science, ML, databases claude plugin install voltagent-infra — DevOps, cloud, Terraform claude plugin install voltagent-lang — language specialists (TS, Python, Go, Rust) claude plugin install voltagent-biz — product, business analysis claude plugin install voltagent-domains — fintech, blockchain, IoT

Or browse via marketplace: /plugin marketplace add VoltAgent/awesome-claude-code-subagents then /plugin install <name>@voltagent-subagents

Continue without them? They're optional — the review will still work with generic persona-prompted agents."

Only suggest installation once per session. List only the families relevant to the detected content signals, not all 10. If the user declines or the agents aren't available, proceed with the generic fallback silently.

Step 4: Launch with subagent_type AND model: "opus". When launching Phase 3 agents:

• subagent_type: "voltagent-qa-sec:code-reviewer", model: "opus" (when available)
• Omit subagent_type, pass model: "opus" explicitly (generic agent fallback)

CRITICAL (v2.14): ALWAYS pass model: "opus" even when using subagent_type. VoltAgent agents may declare their own default model (sonnet, haiku) in their frontmatter. Without an explicit override, the panel silently runs on mixed models, producing different reasoning depths across runs. The VoltAgent agent's value lives in its system prompt and tool access, NOT its default model. Forcing opus preserves the domain expertise while guaranteeing consistent reasoning depth. This fix resolves an invisible source of cross-run variance documented in the v2.10→v2.14 consistency analysis.

The persona prompt is STILL included even when using VoltAgent agents — it provides the review-panel-specific context (agreement intensity, reasoning strategy, evaluation criteria) that the VoltAgent agent doesn't have natively.

---

Live-State Claim Discipline (v3.3.0)

Resolves #40. A panel reading source code can verify what a script or manifest WILL do if executed — it cannot verify what production infrastructure IS doing right now. Conflating the two produced a false-positive P0 "IAM/IAP divergence" finding that survived all 5 reviewers, 3 debate rounds, and the Supreme Judge: the agents read echo "gcloud ... --role=..." lines in two deploy scripts (operator-facing documentation printed to the terminal at deploy-completion time) as if they were the live IAM bindings of the deployed service. A single gcloud run services describe would have falsified it in 30 seconds.

This discipline applies to any finding that asserts a fact about live state — deployed IAM/IAP/auth config, a running cron schedule, a BigQuery table's partition key, a production env var, a load balancer's routing. It is NOT limited to security. It is injected into Phase 3 reviewer prompts, the Phase 5 debate prompt, Phase 11 severity verification, and the Phase 14 judge prompt.

Rule 1 — Declarative vs. imperative vs. documentation

Reviewers must distinguish three things a source file can contain:

Category	Example	What it proves
Declarative config	gcloud run deploy ... --no-allow-unauthenticated, a Terraform resource, a YAML manifest	The deploy WILL create this config if run — still not proof it WAS run
Imperative documentation	echo " gcloud beta run services add-iam-policy-binding ...", a comment, a README snippet, a printed "next steps" blurb	A human is being TOLD to run this later. The script itself does not.
Live state	output of gcloud ... describe / ... get-iam-policy, bq show, aws ... describe-*, kubectl get, crontab -l	What production actually is right now

Lines inside echo "...", print(...), comments, heredocs echoed to a terminal, or string literals in "usage" / "next steps" blocks are documentation, not configuration. They are never evidence for a live-state claim. Configuration claims must come from declarative deploy flags / manifests; live-state claims must come from live describe-class output.

Rule 2 — Live-state claims need live evidence

Every finding that asserts a live-infrastructure or runtime-state fact carries one of two epistemic tags:

• [LIVE-VERIFIED] — backed by output from a live-state command (gcloud ... describe / ... get-iam-policy, bq show, aws ... describe-*, kubectl get, crontab -l, etc.) that the panel actually ran or that the user supplied.
• [STATIC-INFERENCE] — inferred from source code, config files, or deploy scripts only. The panel did not (or could not) observe live state.

A [STATIC-INFERENCE] live-state claim is capped at P1, no matter how many reviewers cite it. P0 ("block the demo") requires [LIVE-VERIFIED] — or the finding must be reworded as "the deploy script would configure X" (a [PLAN_RISK], not an [EXISTING_DEFECT]). When the panel lacks the tools to obtain live evidence, the finding must say so explicitly rather than inferring.

Rule 3 — Consensus does not compound on a shared artifact

When 2+ reviewers reach the same conclusion by reading the same source lines, that is consensus on an interpretation, not independent verification of a fact. It must not be promoted to [VERIFIED] or used to justify P0. Phase 6 (Sycophancy Detection) flags this pattern; the judge tags it [STATIC-INFERENCE-CONSENSUS] and requires independent live verification before any P0 promotion. Cross-citation chains (Security F3 → Architecture F4 → DA CF2) over the same artifact lines are a single source, not three.

Rule 4 — Pre-promotion falsification check

Before any finding is promoted to P0 — in debate (Phase 5) or by the judge (Phase 14) — answer two questions:

1. What single observation would prove this finding wrong?
2. Is that observation cheap to obtain?

If a P0 can be falsified by one read-only command (a describe, a show, a grep) and no agent ran it, the finding is at most P1 until verified. Record the falsification test alongside the finding.

---

Phase 2: Data Flow Trace (v2.14)

A dedicated agent traces data through the critical path(s) of the work BEFORE reviewers begin, producing a structured Data Flow Map. This phase specifically targets composition defects — bugs where two individually- correct functions produce incorrect results together. These bugs are structurally invisible to reviewers who read each function in isolation.

Research foundations: Meta semi-formal certificate prompting (2026, 78%→93% accuracy), LLMDFA (NeurIPS 2024, 87% precision), RepoAudit (ICML 2025, 78% precision with demand-driven exploration), BugLens (ASE 2025, 7x false positive reduction), ZeroFalse (2025, F1 0.955).

Skip Conditions

• Pure plans/design (no code)
• Pure documentation (no code)
• Code with no detectable data transforms (pure API routing, static config, declarative-only files)

When Phase 2 is skipped, note the reason in the Context Brief and the report header. Proceed directly to Phase 3.

Tier System

Three tiers, user-selectable via --trace {tier} or natural language:

Tier	Trigger Phrases	Paths Traced	Overhead	Token Budget
Standard (default)	no modifier, "review"	Single most important path	~5 min	~8k
Thorough	"thorough review", "thorough trace", --trace thorough	Top 3 paths + transform completeness	~15 min	~20k
Exhaustive	"exhaustive review", "trace everything", "catch all bugs", --trace exhaustive	ALL paths from every entry point	No limit	No limit

Tier detection priority:

1. Explicit --trace {tier} flag
2. Natural language keywords in user's original prompt
3. Default: Standard

"Deep review" (which triggers web research) combines with Standard trace unless the user also specifies a trace tier.

Critical Path Identification (orchestrator, not subagent)

Before launching the Data Flow Tracer, the orchestrator identifies entry points and ranks them by data complexity:

1. Find entry points. Scan for structural markers:

   • Web frameworks: @app.route, @router.get/post, @api_view, Django CBVs
   • CLI: @click.command, @app.command (Typer), if __name__ == "__main__":, argparse
   • Background: @app.task (Celery), AWS lambda_handler, Kafka/SQS consumers
   • Scripts: main(), top-level script execution

2. Rank by data complexity. Count on each path:

   • Number of function calls
   • Number of data transforms (map/filter/reduce/apply/merge/join/groupby/pivot)
   • Number of I/O boundaries (DB, HTTP, file, queue)
   • Presence of transform/back-transform pairs

3. Select paths per tier:

   • Standard: top-ranked path only
   • Thorough: top 3 paths
   • Exhaustive: all paths

The Data Flow Tracer Agent

Single agent (model: "opus"). VoltAgent mapping: voltagent-data-ai:data-engineer primary, voltagent-qa-sec:code-reviewer fallback. Always pass model: "opus" even when using subagent_type.

Uses the semi-formal certificate approach from Meta's 2026 agentic code reasoning research. At each function boundary on the critical path, the agent produces a certificate:

FUNCTION: {name} ({file}:{line})
INPUT_SCHEMA:
  - parameter types (declared or inferred)
  - known constraints at call site
  - which parameters are externally controlled
TRANSFORM:
  - what the function does
  - key assignments and branches
  - external calls (I/O, DB, modules)
OUTPUT_SCHEMA:
  - return type
  - tainted/derived fields
  - guaranteed invariants
COMPOSITION_CHECK: (vs next function)
  - Does OUTPUT_SCHEMA satisfy next INPUT_SCHEMA?
  - Fields required but not guaranteed?
  - Tainted fields reaching sensitive parameters?
INVARIANT_STATUS:
  - preserved or violated invariants
  - violations flagged as P0 candidates

See references/prompt-templates.md for the full Phase 2 Data Flow Tracer prompt.

Mandatory Invariant Checks (at every boundary)

1. Schema preservation — output schema matches next function's expected input
2. Transform/back-transform completeness — list forward transforms (log, encode, serialize) and back-transforms (exp, decode, deserialize). Any field in forward but not back is a P0 candidate. See the Transform/Back- Transform Completeness checklist in references/signals-and-checklists.md.
3. Row count stability — joins/merges/reindex/groupby should not silently add or remove rows
4. Null semantics — fillna(0) does not destroy meaningful missingness
5. Temporal consistency — date filters applied to all date columns; ALL instances of an excluded event (e.g., BOTH Christmases) handled

Output and Integration with Phase 3

The Data Flow Tracer produces a Data Flow Map containing:

• List of paths traced
• Per-function certificates
• Invariant violations table (P0 candidates)
• Transform completeness table
• Clean paths (where all invariants hold)

Integration with Phase 3: The Data Flow Map is injected into every reviewer's Phase 3 prompt as dedicated context. Invariant violations are flagged as P0 candidates; reviewers must either validate them (agree they're real P0s) or explicitly challenge them with reasoning. Reviewers are NOT required to agree with the tracer — this is an additional input, not a mandate.

When no violations are found, reviewers receive a short "clean trace" confirmation instead.

---

Phase 3: Independent Review (Round 0)

Launch ALL reviewer agents in parallel using Agent tool with model: "opus". When VoltAgent integration is active, use subagent_type from the mapping table. Each gets the structured prompt from references/prompt-templates.md (Phase 3 template) with their persona, agreement intensity, reasoning strategy, context brief, and the full work content inside injection boundaries. The prompt also carries the Live-State Claim Discipline (Rules 1–2): reviewers must tag every live-infrastructure/runtime-state claim [LIVE-VERIFIED] or [STATIC-INFERENCE] and must not treat echo/comment/usage-blurb lines as configuration.

Collect all N independent reviews.

Output (v3.1.0+): Each reviewer subagent writes its full review to state/reviewer_<name>_phase_3.md and returns only the path + a ≤50-word summary. The orchestrator does NOT hold verbatim reviews in its window.

Persistent reviewers (v3.8.0): these Phase 3 spawns are the ONLY reviewer spawns of the run — Phases 4, 5, and 7 are driven by SendMessage to these same agents (see Orchestrator Efficiency Discipline). If SendMessage to an agent fails or is unavailable, fall back to a fresh spawn that reads that persona's prior state files from disk.

---

Phase 4: Private Reflection

Send the Phase 4 prompt to each persistent reviewer agent via SendMessage (all sends batched in one message; fresh-spawn fallback reads the persona's Phase 3 state file). Each works from ONLY their own review. They re-read source, rate confidence per finding (High/Medium/Low), note new issues, identify most/least defensible findings. See references/prompt-templates.md.

Output (v3.1.0+): Each reviewer's reflection is written to state/reviewer_<name>_phase_4.md. Subagent returns only path + ≤50-word summary.

---

Phase 5: Debate (Rounds 1-3, adaptive)

Each round, send the debate prompt to every persistent reviewer agent via SendMessage (all sends batched in one message; fresh-spawn fallback reads the persona's prior state files). Each receives their own review + reflection, all others' feedback, and unresolved points from previous round.

Output (v3.1.0+): Each reviewer's per-round debate response is written to state/reviewer_<name>_phase_5_round<R>.md (R = 1, 2, or 3). Round 1 is mandatory; rounds 2 and 3 follow the existing convergence-based skip rules. Subagent returns only path + ≤50-word summary.

Pre-promotion falsification check (v3.3.0). Before any finding is promoted to — or kept at — P0 in any debate round, the reviewer must state the single observation that would falsify it and whether that observation is cheap to obtain (see Live-State Claim Discipline Rule 4). A P0 that one read-only command could falsify, with no agent having run it, is capped at P1 until verified.

Phase 6: Round Summarization

After each round, summarize (no agent needed):

• Resolved this round — who agreed, what convinced them
• Still in dispute — with inlined source excerpts (max 10 lines per dispute, first 5 + last 5 if longer; max 3 disputes). If a reviewer's claim cannot be traced to a specific source location, tag [source not cited by reviewer].
• New discoveries — from which reviewer

Sycophancy Detection (CONSENSAGENT)

Count position changes toward majority. If >50% lack new evidence → inject sycophancy alert into next round prompt for all reviewers.

Shared-artifact consensus (v3.3.0). Also flag when 2+ reviewers agree on a claim by reading the same source lines without independent verification — including cross-citation chains where each reviewer cites the previous one's finding rather than the source. This is consensus on an interpretation, not on a fact: it does not compound to [VERIFIED] and must not justify P0. Tag such points [STATIC-INFERENCE-CONSENSUS] (Live-State Claim Discipline Rule 3) and route them to verification before any P0 promotion.

Convergence Check

• All disputes minor/stylistic → stop
• Substantive disagreements remain → continue
• New discoveries still emerging → continue
• Maximum 3 rounds regardless

---

Phase 7: Blind Final Assessment

Send the blind-final prompt to every persistent reviewer agent via SendMessage, one final time (batched; fresh-spawn fallback as above). Each gives final score, top 3 points, recommendation, one-line verdict. Others do NOT see these.

Output (v3.1.0+): Each reviewer's blind final is written to state/reviewer_<name>_phase_7.md. Subagent returns only path + ≤50-word summary of new findings.

---

Phase 8: Completeness Audit

Single agent (model: "opus") hunts for what the entire panel missed. Does NOT evaluate quality — only finds overlooked details, edge cases, constants, code. See references/prompt-templates.md for full prompt.

Mandatory audit checks (in addition to general completeness):

• Temporal scope verification: For every claim that excludes, filters, or masks a time period, count all instances in the full date range and verify each is handled. Example: "excludes Christmas" with 2 years of data must exclude BOTH Christmases. This is the #1 class of bug that reviewers miss because they focus on the method, not the temporal arithmetic.

Output (v3.1.0+): Subagent writes full output to state/phase_8_audit.md and returns only path + ≤50-word summary.

---

Phase 9: Verification Command Execution (v2.8)

Run up to 5 reviewer verification_command entries for P0/P1 findings (P0 first). Validate read-only (grep/cat/head/tail/wc only), execute via Bash, annotate: [CMD_CONFIRMED], [CMD_CONTRADICTED] (demote 1 level), [CMD_INCONCLUSIVE], [CMD_FAILED]. Advisory, not gating — demotes but does not delete. Skip this phase if no verification commands were provided.

---

Phase 10: Claim Verification

Single agent (model: "opus") checks all reviewer citations against source. Classifies each as [VERIFIED], [INACCURATE], [MISATTRIBUTED], [HALLUCINATED], or [UNVERIFIABLE]. Results feed into judge prompt.

Output (v3.1.0+): Subagent writes full output to state/phase_10_claim_verification.md and returns only path + ≤50-word summary.

---

Phase 11: Severity Verification (v2.7)

Single agent (model: "opus") that reads the actual codebase to verify every P0 and P1 finding before the judge sees them. This phase exists because panels systematically overstate severity when they lack runtime context (v2.6 benchmark: 2/3 P0 findings were overstated after code investigation).

For each P0/P1 finding, the agent must:

1. Classify as [EXISTING_DEFECT] or [PLAN_RISK]
   • [EXISTING_DEFECT]: The bug exists in the current running code right now
   • [PLAN_RISK]: The risk would only materialise if the plan is implemented as written
   • P0 severity requires [EXISTING_DEFECT]. A [PLAN_RISK] is at most P1.

1b. Live-state claim classification (v3.3.0) — If the finding asserts a fact about live infrastructure or runtime state (deployed IAM/IAP/auth config, a running cron schedule, a production env var, a BigQuery partition key, a load balancer's routing), apply the Live-State Claim Discipline:

• Tag [LIVE-VERIFIED] only if backed by live describe-class command output the panel ran or the user supplied; otherwise tag [STATIC-INFERENCE].
• A [STATIC-INFERENCE] live-state claim is capped at P1 regardless of reviewer count. Do NOT let it stay P0 on consensus alone.
• Reject echo/comment/usage-blurb lines as evidence — those are documentation, not configuration. A claim resting only on such lines is [STATIC-INFERENCE] at best and is frequently [INACCURATE].

2. Verify the claim against actual code

   • If the finding says "X is missing", grep for X in the actual codebase
   • If the finding says "X pattern is wrong", read the referenced code and check
   • If the finding cites a specific file/line, read that file and verify
   • If no reviewer cited a specific line number, flag as [UNCITED]

3. Check for existing safety mechanisms

   • Grep for DELETE, MERGE, upsert, idempotent, dry-run, duplicate, assertion patterns near the referenced code
   • A finding about "missing safety" is invalid if the safety exists but the reviewer didn't look for it

4. Output a severity verification table:

| Finding | Panel Severity | Verified? | Actual Severity | Reason |
|---------|---------------|-----------|-----------------|--------|
| ...     | P0            | No        | Not a bug       | Grep found no bf/af COALESCE pattern |
| ...     | P0            | Partial   | P1              | DELETE-then-INSERT already exists |

5. External domain claim detection and web verification (v2.16.3)

   Why this exists: Consensus P0 findings that depend on external domain knowledge bypass the Phase 12/13 dispute-verification pipeline entirely (because there is no dispute to trigger it). But all reviewers can be wrong the same way — shared model bias or shared domain knowledge gaps. In a real engagement (PUMA GA4 audit, 2026-04-09), all 4 reviewers unanimously flagged "50 months = GA4 360" as P0 without verifying whether 50 months is even a valid GA4 setting. The claim happened to be correct, but the panel had no mechanism to verify it. If the source data had been wrong, the panel would have confidently presented an incorrect P0.

   For each P0/P1 finding, classify whether it depends on external knowledge:

   • External domain claim: The finding's validity depends on facts outside the reviewed codebase — product feature limits, API behavior, regulatory jurisdiction, pricing tiers, platform capabilities, protocol specifications, third-party documentation. Examples: "50 months retention means GA4 360", "GDPR applies to Mexico", "this API rate-limits at 100 req/s."
   • Internal claim: The finding is fully verifiable from the reviewed code, config, or documentation. No external knowledge needed.

   For each finding classified as external domain claim:

   • Run a web search to verify the specific factual premise (cap: 2 searches per claim, 5 claims max per review)
   • Tag result: [WEB-VERIFIED] (confirmed by authoritative source), [WEB-CONTRADICTED] (external source disagrees — demote severity by 1 level), [WEB-INCONCLUSIVE] (no authoritative source found — flag for judge)
   • Include the source URL and key quote in the verification table
   • Regulatory/jurisdiction claims (e.g., "GDPR applies to X country") are ALWAYS classified as external domain claims

   Extended severity verification table:

   | Finding | Severity | Domain Type | Web Result | Source | Adjusted Severity |
   |---------|----------|-------------|------------|--------|-------------------|
   | ...     | P0       | External    | [WEB-VERIFIED] | support.google.com/... | P0 (confirmed) |
   | ...     | P1       | External    | [WEB-CONTRADICTED] | gdpr.eu/... | P2 (demoted) |
   | ...     | P0       | Internal    | N/A        | N/A    | P0 (code-verified) |
   

   Skip condition: If all P0/P1 findings are internal claims (fully verifiable from the reviewed content), skip web verification.

Results feed into the Supreme Judge prompt. The judge MUST reference the verification table when ruling on disagreements.

Output (v3.1.0+): Subagent writes full output to state/phase_11_severity_verification.md and returns only path + ≤50-word summary.

---

Phase 12: Verification Tier Assignment (v2.11)

After Phases 8–11, collect all unresolved dispute points from Phase 6 summaries plus any high-uncertainty action items bearing [SINGLE-SOURCE], [DISPUTED], or [UNVERIFIED] labels. Each point is assigned a depth tier that controls the verification agent's budget and capabilities in Phase 13.

Skip condition: If there are zero unresolved disputes and zero unverified action items, skip Phases 12 and 13 entirely.

Tier Definitions

Tier	Budget	Capabilities	When to Use	Example
Light	~2k tokens	grep/read only, no web search	Factual claim checkable in a single file or constant lookup	"Reviewer A claims the threshold constant is 0.05 but the report says 0.5 — check the code."
Standard	~8k tokens	Multi-file reads, import tracing, static analysis	Claim requires following logic across files or comparing multiple outputs	"Two reviewers disagree on whether the rate-limiter handles concurrent requests — trace the implementation across its dependencies."
Deep	~32k tokens	Web search, multi-round reasoning	Requires external knowledge, novel domain, or fundamental disagreement unresolvable from code alone	"Security reviewer claims the PRNG is cryptographically weak for this use case — requires researching current best practices for the specific algorithm."

Assignment Pipeline (default: both steps; quick mode: step 1 only)

Tier assignment runs as a two-step pipeline. Step 1 is always fast; step 2 (the judge refinement) is the default but can be skipped by requesting "quick tier assignment" or "confidence-based tiers only".

Step 1 — Confidence-Based Draft (always runs; no agent needed):

The orchestrator derives initial tier assignments from existing Phase 4 confidence ratings and debate round signals:

• Deep: Any reviewer rated the claim Low confidence in Phase 4, OR the point remained unresolved across 2+ debate rounds, OR the claim requires external or runtime knowledge (e.g., production behavior, third-party API semantics, literature validation)
• Standard: Any reviewer rated Medium/mixed confidence, OR unresolved for exactly 1 debate round, OR claim requires cross-file logic tracing
• Light: All reviewers rated the claim High confidence AND it is a simple checkable fact (file exists, value matches, line present)

Produces a draft tier table:

| Point # | Summary | Draft Tier | Signal (confidence ratings + rounds unresolved) |
|---------|---------|------------|------------------------------------------------|

Step 2 — Judge-Advised Refinement (default: on):

A single Opus agent (Phase 12b) receives the confidence-based draft table and all supporting context (context brief, Phase 6 summaries, Phase 7 blind finals, completeness audit, claim and severity verification results). Its job is to review and refine the draft — upgrade, downgrade, or confirm each tier with reasoning. It also assigns the verification persona per point.

The advisor works from the draft rather than from scratch: the confidence ratings give it the "ground-level" signal from reviewers who lived through the debate, and the advisor's role is oversight and correction, not cold assessment from zero.

Final tier table:

| Point # | Summary | Draft Tier | Final Tier | Override Reason | Suggested Persona |
|---------|---------|------------|------------|-----------------|-------------------|

---

Phase 13: Targeted Verification Agents (v2.11)

Dispatch one verification agent per collected dispute/action item. All Light and Standard agents launch in parallel; Deep agents can also parallelize unless they share a scarce resource (e.g., web search rate limits).

Persona Matching

Classify each claim's type and select the matching verification persona. VoltAgent agents are preferred when available; fall back to generic + focused prompt.

Claim Type	Verification Persona	VoltAgent (preferred)
Statistical / numerical	Data Scientist	voltagent-data-ai:data-scientist
Code correctness / logic	Code Reviewer	voltagent-qa-sec:code-reviewer
Architecture / design	Architect Reviewer	voltagent-qa-sec:architect-reviewer
Security vulnerability	Security Auditor	voltagent-qa-sec:security-auditor
Performance / scalability	Performance Engineer	voltagent-qa-sec:performance-engineer
Database / SQL	Database Expert	voltagent-data-ai:database-optimizer
Infrastructure / ops	SRE	voltagent-infra:sre-engineer
Framing / narrative	Domain expert	Generic + domain context
Business logic / feasibility	Business Analyst	Generic + business context
Default / unclear	Verification Agent	Generic + focused prompt

Capability Limits by Tier

• Light (~2k tokens): May only grep/read/head/tail. Single focused query. Return one of [VR_CONFIRMED], [VR_REFUTED], [VR_INCONCLUSIVE] with one piece of quoted evidence. Do not expand scope beyond the specific claim.
• Standard (~8k tokens): May read multiple files, trace imports, run static analysis commands. Return verdict with supporting evidence from multiple sources. Explore adjacent code only if directly relevant to the dispute.
• Deep (~32k tokens): Full agent capabilities including web search and multiple reasoning rounds. Return a comprehensive verdict; cite external sources when they resolve the dispute. Scope limited to the specific dispute — do not produce a second full review.

Verdict Labels

• [VR_CONFIRMED] — Evidence confirms the original claim
• [VR_REFUTED] — Evidence contradicts the claim
• [VR_PARTIAL] — Claim is partially supported; the agent qualifies what holds
• [VR_INCONCLUSIVE] — Insufficient evidence to verify either way
• [VR_NEW_FINDING] — Verification revealed an additional issue beyond the dispute

Verification Round Summary

After all agents complete, compile into a summary table:

| Point | Tier | Persona | Verdict | Key Evidence |
|-------|------|---------|---------|--------------|

This table is passed to Phase 14 as input item 8.

---

Phase 13.5: Pre-Judge Verification Gate (v3.1.0)

Before launching the Supreme Judge (Phase 14), the orchestrator MUST verify that all mandatory phase outputs exist on disk. This gate is the load-bearing guardrail against silent compression of Phases 4 / 5 / 7.

Gate logic (orchestrator-executed, no subagent dispatch):

For each reviewer in the panel, verify these files exist under state/ (or state/run_<N>/ in multi-run mode):

Required file	Phase	Mandatory
reviewer_<name>_phase_3.md	Independent review	Always
reviewer_<name>_phase_4.md	Private reflection	Always
reviewer_<name>_phase_5_round1.md	Debate round 1	Always (rounds 2/3 per existing skip rules)
reviewer_<name>_phase_7.md	Blind final	Always

Plus panel-level files:

• phase_8_audit.md
• phase_10_claim_verification.md
• phase_11_severity_verification.md

For each required file, run three checks:

1. Existence check — file is present on disk.
2. Minimum-bytes check — file size ≥ 500 bytes. Below this is empirically a stub (subagent crashed mid-write or returned a placeholder).
3. Required-headers check — parse the file and confirm it contains the required schema sections for that phase (e.g., a Phase 3 review must contain a Score, a Findings section, and severity tags). The exact required sections per phase are defined in references/prompt-templates.md.

On gate failure for any file:

1. Log loudly: GATE FAIL: <file> missing | stub | malformed
2. Re-dispatch the subagent for the missing/malformed phase output.
3. Re-run the gate after re-dispatch.
4. Single retry only. If the second attempt also fails, do NOT block the run. Mark the phase as unrecoverable, write the COMPRESSED RUN header in Phase 15.1 (see Phase 15.1 spec), and proceed to Phase 14 with the partial input. The deliverable is produced with explicit warning rather than failing entirely — partial review with loud warning beats no review.

On full gate pass: proceed to Phase 14. The COMPRESSED RUN header is NOT emitted (its absence is the green light).

Debate-presence assertion (v3.5.0) — distinct from per-file compression. The per-file gate above re-dispatches an individual missing file. But the dominant real-world failure (2026-06-06 audit: 50/51 runs had no debate) is the wholesale skip — the orchestrator never ran Phase 5 at all and jumps from independent reviews straight to the judge. So, separately from the per-file check, count the reviewer_*_phase_5_round1.md files across the whole panel (or state/run_<N>/ in multi-run mode):

• If the count is ZERO when mode = full panel (the entire debate phase is absent, not just one reviewer's file), this is the NO-DEBATE condition. Do NOT proceed to Phase 14 silently. Instead:
  1. Preferred — run Phase 5 now. Debate was skipped; execute it (round 1 is non-skippable per the protocol) and re-run this assertion.
  2. If debate is genuinely unavailable for this execution shape (e.g., the run is executing as a parallel Workflow / ultracode fan-out with no sequential cross-talk primitive — see Debate inside a Workflow below), stamp the [NO-DEBATE] banner (Phase 15.1 / 15.3) and lower the verdict confidence (cap at Medium). The judge still rules, but the report announces that no adversarial cross-examination happened.
• If the count is ≥ 1, debate ran; no NO-DEBATE banner. (Individual missing round-1 files for some reviewers remain a per-file COMPRESSED case, handled above.)

Detection is not solely anchored here. Phase 13.5 does not fire on every execution shape (an inline/workflow-shaped run can skip this gate entirely — that is exactly how the audit's silent skips slipped through). The load-bearing NO-DEBATE check therefore also runs at the Phase 15.1 report-write chokepoint (every completed run passes through it). See Phase 15.1.

Why bytes + headers, not just existence: A subagent can write a stub and crash, leaving an empty/partial file. Existence alone passes the gate on a stub. Bytes + required-headers makes the check load-bearing. This mirrors how the Phase 15 verification gate (v2.16.4) validates HTML output structurally, not just by file presence.

---

Phase 14: Supreme Judge

Single agent (model: "opus"). The launch prompt is ~200 tokens of metadata: the paths to the state files produced by Phases 3, 4, 5, 7, 8, 10, 11, and 13. The judge reads state files on demand using the Read tool — it does NOT receive verbatim phase outputs pre-stuffed into its launch prompt. This mirrors the Phase 15.3 HTML-agent pattern (v2.16.4) and caps the judge's window load even when the panel has produced hundreds of kilobytes of material.

The judge's ruling is materialized to state/phase_14_judge_ruling.md so Phase 15.1 can later consume it from disk (rather than from chat).

Steps (in order): 0. Review verification results (claims, severity, commands, and verification round) 0.5a-b. Verify audit findings, anti-rhetoric assessment 0.5c. Severity dampening — minimum evidence-justified severity. In Precise mode, findings without code citations cannot exceed P2. Live-State Claim Discipline (v3.3.0): a live-infrastructure/runtime-state claim tagged [STATIC-INFERENCE] cannot exceed P1, and a P0 that one cheap read-only command could falsify (with no agent having run it) is capped at P1 until verified. 0.5d. Coverage check — flag unexamined risk categories, scan source for gaps 1-3. Debate quality, disagreement rulings, consensus correctness. A [STATIC-INFERENCE-CONSENSUS] point — multiple reviewers agreeing off the same artifact lines — counts as one source, not independent verification. 4-5. Absent-safeguard check, independent gap scan, score assessment 6-7. Epistemic label classification (including [LIVE-VERIFIED] / [STATIC-INFERENCE] / [STATIC-INFERENCE-CONSENSUS] for live-state claims), final verdict 8-9. Action items, meta-observation 10. Write ruling to {state_dir}/phase_14_judge_ruling.md (v3.1.0+).

See references/prompt-templates.md for the full judge prompt.

---

Phase 14.5: Post-Judge Verification Gate (v3.2.0)

The Supreme Judge in Phase 14 can introduce new P0/P1 findings as a side effect of its Step-0 Verification Review — findings the panel never raised. Phase 11 (Severity Verification) only re-verifies panel-raised P0/P1, so judge-introduced findings bypass every prior verification phase. A 2026-04-27 README review run produced a hallucinated "12 unresolved git conflict markers" P0 (the file was clean — wc -l and grep -c both confirmed) and that single fabricated finding drove a 3/10 REJECT-AND- REWRITE verdict (issue #41).

Phase 14.5 closes this gap by re-verifying every judge-introduced P0/P1 against ground truth before Phase 15.1 generates the report.

A single Opus agent runs after Phase 14 and before Phase 15.1. Inputs are the paths to {state_dir}/phase_14_judge_ruling.md, {state_dir}/phase_11_severity_verification.md, and {state_dir}/phase_8_audit.md. The agent has grep / Read / Bash tools.

Budget mode (v3.7.0): no agent is spawned. The orchestrator itself diffs the judge's P0/P1 list against the union of reviewer + consolidated-verifier P0/P1s, runs 1–2 direct grep/Read probes on any [JUDGE-INTRODUCED] finding, and demotes unverifiable ones to [JUDGE-UNVERIFIED] open questions. The protection is preserved; the agent spin-up is not.

Steps:

1. Classify each P0/P1 finding in the judge ruling as [PANEL-RAISED] (skip — covered by Phase 11) or [JUDGE-INTRODUCED] (verify here).
2. For every [JUDGE-INTRODUCED] finding, run a ground-truth check appropriate to the claim type (location, state, existence, external domain) using grep/Read/git/Bash. Quote actual command output.
3. Issue a verdict per finding: [JUDGE-CONFIRMED] (passes through), [JUDGE-HALLUCINATED] (demote to P3 or remove if actively contradicted), or [JUDGE-PARTIAL] (demote one level, edit to retain only the replicated sub-claim).
4. If any P0 was demoted/removed, recompute the verdict score against the panel mean and document the override.
5. Write the full verification table to {state_dir}/phase_14_5_judge_verification.md. Phase 15.1 reads it.

Phase 15.1 banner. When the gate produces any [JUDGE-HALLUCINATED] entry, Phase 15.1 MUST emit this block immediately after the Executive Summary (and after the Compressed Run banner if present):

> ⚠️ **Judge Verification:** N judge-introduced finding(s) flagged as
> [JUDGE-HALLUCINATED] in Phase 14.5. Verdict score replaced with panel
> mean (X/10 → Y/10). Affected action items below carry the
> [JUDGE-HALLUCINATED] suffix.

Affected action items keep the [JUDGE-HALLUCINATED] epistemic-label suffix in both the markdown report and the HTML dashboard expandable issue card metadata.

Empty case. If the gate produces zero [JUDGE-INTRODUCED] findings (every P0/P1 was already panel-raised), it writes a stub file with the single line "No judge-introduced findings to verify" so Phase 15.1's disk-read still succeeds.

See references/prompt-templates.md for the full Judge-Output Verification Agent prompt.

---

Phase 15: Output Generation

Three output files are written at the end of every review. They are produced in strict sequence: Phase 15.1 first, then Phase 15.2, then Phase 15.3. Phase 15.3 runs AFTER Phase 15.2 (not in parallel) so that the Phase 15.3 agent can read the already-written Phase 15.1 and 15.2 files from disk, avoiding the need for the orchestrator to inject all structured data and process history into the agent prompt from its own context window.

---

Phase 15.1: Primary Markdown Report

Write structured summary to review_panel_report.md (or user-specified name). This is the main deliverable — concise, structured, action-oriented.

Compressed-run warning (v3.1.0+): If the Phase 13.5 verification gate detected any unrecoverable missing phase output, Phase 15.1 MUST emit this block as the FIRST content of the report (before any other section, including Executive Summary):

> ⚠️ **COMPRESSED RUN — Phases skipped: <comma-separated list, e.g., "4 (security), 5 (security, devils-advocate)">**
>
> This run did not complete the full panel protocol. The Supreme Judge ruled
> on partial input. Findings below should be treated as **lower confidence**
> than a full-run report. Re-run the panel for a complete review.

Additionally, in compressed runs, every action item MUST have [COMPRESSED] appended to its epistemic label (e.g., [CONSENSUS][COMPRESSED], [VERIFIED][COMPRESSED]).

For full runs, the warning block is absent. Its absence is the green-light signal that the panel completed the full protocol.

No-debate warning (v3.5.0) — the load-bearing debate-skip chokepoint. Phase 15.1 is the terminal step every completed run passes through, so the NO-DEBATE detection is anchored HERE (not only in the Phase 13.5 gate, which an inline/workflow-shaped run can skip — that is precisely how the audit's silent skips slipped past). Before writing the report, the orchestrator MUST independently check whether any reviewer_*_phase_5_round1.md state files exist (under state/, or any state/run_<N>/ in multi-run mode). If none exist — the adversarial debate (Phase 5) did not run for this panel — Phase 15.1 MUST emit this block as report content (immediately AFTER the COMPRESSED RUN block if one is present, otherwise FIRST, before the Executive Summary):

> ⚠️ **[NO-DEBATE] — adversarial debate (Phase 5) did not run.**
>
> Reviewers evaluated independently but never cross-examined each other's
> findings. The Supreme Judge reconciled disagreements alone, without a debate
> record. Treat consensus and disagreement rulings as **lower confidence** —
> no reviewer had the chance to revise a verdict in light of a peer's. For a
> high-stakes or adversarial-tradeoff decision, re-run the **full** panel with
> debate (invoke as a skill, not a workflow), or use the debate-in-Workflow
> recipe.

In a no-debate run:

• Every action item MUST have [NO-DEBATE] appended to its epistemic label (e.g., [CONSENSUS][NO-DEBATE], [SINGLE-SOURCE][NO-DEBATE]).
• The **Confidence:** header field MUST be capped at Medium (if the judge ruled High, lower it one level to Medium and note why); a no-debate run can never report High confidence.
• The "Debate Rounds + Summaries" collapsible in Detailed Reviews renders the placeholder "No debate rounds — Phase 5 did not run for this panel."

Banner stacking & the COMPRESSED overlap. COMPRESSED (per-file loss) and NO-DEBATE (wholesale Phase-5 absence) are distinct signals and stack: when both apply, render NO-DEBATE first (it is the more specific, higher-severity signal for the verdict), then COMPRESSED. NO-DEBATE is the named signal for zero Phase-5 output, so a COMPRESSED block need not also enumerate "5" in its phases-skipped list when the NO-DEBATE banner is present. For full runs where debate ran, the NO-DEBATE block is absent; its absence is the green-light signal that adversarial debate occurred.

Budget-mode banner (v3.7.0). When the run used budget mode, Phase 15.1 MUST additionally render the [BUDGET-MODE] banner defined in the Budget Mode section. Stacking order when several apply: [NO-DEBATE] first, then COMPRESSED RUN, then [BUDGET-MODE]. A budget run that completed its single debate round gets ONLY the [BUDGET-MODE] banner.

# Review Panel Report
**Work reviewed:** {title/path}  |  **Date:** {today}
**Panel:** {N} reviewers + Auditor + Judge
**Verdict:** {recommendation}  |  **Confidence:** {High|Medium|Low}
**Auto-detected signals:** {list or "None — base set used"}
**Review mode:** {Precise|Exhaustive|Mixed} (auto-detected from content type)
**Data flow trace:** {Standard|Thorough|Exhaustive} tier | {N} paths traced | {M} invariant violations (v2.14)
{If skipped: "**Data flow trace:** Skipped ({reason — pure docs / no transforms / plan-only})"}
**Codebase state:** {branch name} | {N commits behind {default_branch}} | {worktree: yes/no}
{If multi-run: "**Runs:** {N} (personas rotated per schedule)"}
{If multi-run: "**Run stability:** {X}% of findings appeared in 2+ runs | {Y} single-run findings"}
{If stale: "⚠️ STALE BRANCH — {N} commits merged to {default_branch} since branch point. Findings about missing code should be verified against {default_branch}."}

## Executive Summary
{Judge's verdict, 3-5 sentences. Score X/10.}
{If score spread < 2: Correlation Notice about shared model biases}
{If Low confidence: "⚠️ HUMAN REVIEW RECOMMENDED"}

## Scope & Limitations
{What was reviewed. What CANNOT be evaluated: runtime behavior, production
data, security via dynamic analysis. Structural limitation: shared base model.}
Epistemic labels: [VERIFIED] [CONSENSUS] [SINGLE-SOURCE] [UNVERIFIED] [DISPUTED] [WEB-VERIFIED] [WEB-CONTRADICTED] [WEB-INCONCLUSIVE] [JUDGE-HALLUCINATED] [LIVE-VERIFIED] [STATIC-INFERENCE] [STATIC-INFERENCE-CONSENSUS]
Defect type labels: [EXISTING_DEFECT] (bug in current code) [PLAN_RISK] (risk if plan is implemented as written)

## Score Summary
| Reviewer | Persona | Intensity | Initial | Final | Recommendation |

## Consensus Points
{Bullet list of points all/most reviewers agreed on, confirmed by judge}

## Disagreement Points (with judge rulings)
{Each disagreement: Side A, Side B, Verification Round result if run, Judge's ruling with reasoning}

## Completeness Audit Findings
{New issues found by auditor, verified by judge}

## Coverage Gaps (if any)
{Risk categories no reviewer examined, with judge's independent assessment}

{If multi-run: "## Run Comparison"}
{If multi-run: Table showing which findings appeared in which runs, with stability labels}

## Action Items (with severity AND epistemic labels{, and stability labels if multi-run})

## Detailed Reviews (collapsible sections)
- Data Flow Map (Phase 2, v2.14) — if tracer ran
- Round 0: Independent Reviews
- Private Reflections
- Debate Rounds + Summaries
- Final Blind Assessments
- Completeness Audit
- Verification Command Execution Results
- Claim Verification Report
- Severity Verification Table
- Verification Tier Assignment (4.8)
- Targeted Verification Results (4.9)
- Supreme Judge Full Analysis

---

Phase 15.2: Full Agent Process History

Write review_panel_process.md — the "director's cut". This is a complete, chronological, verbatim log of every agent's output with nothing summarized away. The orchestrator assembles this from accumulated outputs; no new agent needed.

Persona profiles are embedded at the point each agent first enters the flow: before each agent's output, a structured "Persona Profile" block documents that agent's role, expertise, reasoning strategy, agreement intensity (for panelists), matched-claim-type (for Phase 13 agents), and which phases they participated in. This makes the process history fully self-explanatory to a reader who wasn't present.