How many files, users, or systems a finding's defect could affect
slopsquatting
AI-hallucinated package names in dependencies — security-critical, checked first in Wave 2
research validation
Core differentiator: every non-trivial finding confirmed with external evidence (Context7, WebSearch, DeepWiki, gh). Two evidence tiers: fact evidence (Grep) for reuse/simplification findings; assumption evidence (external research) for correctness, security, and non-obvious design.
systemic finding
A pattern appearing in 3+ files, elevated from individual findings during Judge reconciliation
approval gate
Mandatory pause after presenting findings — never implement fixes without user consent
pass
Internal teammate stage (Pass A: scan, Pass B: deep dive, Pass C: research) — distinct from pipeline waves
self-verification
Wave 3.5: adversarial pass on top findings to reduce false positives (references/self-verification.md)
convention awareness
Check for AGENTS.md/CLAUDE.md/.cursorrules — review against project's own agent instructions
code reuse finding
newly written code duplicating existing functionality; must cite existing implementation at file:line.
fact evidence
Grep result confirming X exists/doesn't exist in the codebase. Sufficient for reuse/simplification findings — no external research required.
assumption evidence
external research (WebSearch, Context7) confirming a pattern is harmful. Required for correctness, security, and non-obvious design findings.
degraded mode
Operation when research tools are unavailable — confidence ceilings applied per tool
review depth
honest-review always operates at maximum depth — all lenses, full research validation, full team; team composition is content-adaptive (file types determine specialist selection).
reasoning chain
Mandatory explanation of WHY before the finding statement. Reduces false positives.
citation anchor
[file:start-end]
reference linking a finding to specific source lines. Mechanically verified.
conventional comment
Structured PR output label: praise/nitpick/suggestion/issue/todo/question/thought with (blocking)/(non-blocking) decoration.
dependency graph
Import/export map built during Wave 0 triage. Informs blast radius and cross-file impact.
learning
A stored false-positive dismissal that suppresses similar future findings. Scoped per project.
Dispatch
$ARGUMENTS
Mode
Empty + changes in session (git diff)
Session review of changed files
Empty + no changes (first message)
Full codebase audit
File or directory path
Scoped review of that path
"audit"
Force full codebase audit
PR number/URL
Review PR changes (gh pr diff)
Git range (HEAD~3..HEAD)
Review changes in that range
"history" [project]
Show review history for project
"diff" or "delta" [project]
Compare current vs. previous review
--format sarif
(with any mode)
Output findings in SARIF v2.1 (references/sarif-output.md)
"learnings" [command]
Manage false-positive learnings (add/list/clear)
--format conventional
(with any mode)
Output findings in Conventional Comments format
Unrecognized input
Ask for clarification
Review Posture
Severity calibration by project type
:
Prototype: report P0/S0 only. Skip style, structure, and optimization concerns.
Production: full review at all levels and severities.
Library: full review plus backward compatibility focus on public API surfaces.
Confidence-calibrated reporting
:
Every finding carries a confidence score (0.0-1.0). Confidence ≥ 0.7: report.
Call out well-engineered patterns, clean abstractions, and thoughtful design.
Minimum one strength per review scope. Strengths are findings too.
Positive-to-constructive ratio
:
Target 3:1. Avoid purely negative reports. If the ratio skews negative,
re-examine whether low-severity findings are worth reporting.
Exception: when 3+ P0/P1 findings are present, report all critical findings without reducing them to meet the ratio — critical issues are never suppressed for balance.
Convention-respecting stance
:
Review against the codebase's own standards, not an ideal standard.
Healthy codebase acknowledgment
:
If no P0/P1 or S0 findings: state this explicitly. A short report is a good report.
Review Levels (Both Modes)
Three abstraction levels, each examining defects and unnecessary complexity:
Correctness
(does it work?):
Error handling, boundary conditions, security, API misuse, concurrency, resource leaks.
Simplify: phantom error handling, defensive checks for impossible states, dead error paths. TOCTOU anti-pattern: existence checks before operations create race conditions — operate directly, handle the error.
Design
(is it well-built?):
Abstraction quality, coupling, cohesion, test quality, cognitive complexity.
Simplify: dead code, 1:1 wrappers, single-use abstractions, over-engineering. Stringly-typed (raw strings where constants/enums already exist). Parameter sprawl (new params instead of restructuring). Redundant state (duplicates existing state or derivable). Copy-paste variation (near-identical blocks that should be unified).
Efficiency
(is it economical?):
Algorithmic complexity, N+1, data structure choice, resource usage, caching.
Simplify: unnecessary serialization, redundant computation, premature optimization. Hot-path bloat (blocking work on startup or per-request paths). Missed concurrency (independent ops run sequentially). Overly broad operations (reading entire file/collection when only a subset is needed). Unbounded structures / event-listener leaks.
Context-dependent triggers (apply when relevant):
Security: auth, payments, user data, file I/O, network
Never state a finding without first explaining the reasoning.
Citation anchors are mechanically verified — the referenced lines must exist and contain
the described code. If verification fails, discard the finding.
Research Validation
THIS IS THE CORE DIFFERENTIATOR. Do not report findings based solely
on LLM knowledge. For every non-trivial finding, validate with research:
Three-phase review per scope
:
Flag phase
Analyze code, generate hypotheses
Verify phase
Before reporting, use tool calls to confirm assumptions:
Grep for actual usage patterns claimed in the finding
Read the actual file to confirm cited lines and context
Check test files for coverage of the flagged code path
If code does not match the hypothesis, discard immediately
Validate phase
Spawn research subagents to confirm with evidence:
Context7: library docs for API correctness
WebSearch (Brave, DuckDuckGo, Exa): best practices, security advisories
DeepWiki: unfamiliar repo architecture and design patterns
WebFetch: package registries (npm, PyPI, crates.io)
gh: open issues, security advisories
Assign confidence score (0.0-1.0) per Confidence Scoring Rubric
Only report findings with evidence. Cite sources.
Two evidence tiers:
Fact evidence
— Grep confirms X exists/doesn't in the codebase; sufficient for reuse and simplification findings.
Assumption evidence
— external research confirming a pattern is harmful; required for correctness, security, and non-obvious design. When in doubt: if the finding can be fully proven or disproven by reading the codebase alone, fact evidence suffices.
Research playbook: read references/research-playbook.md
Mode 1: Session Review
Session Step 1: Triage (Wave 0)
Run
git diff --name-only HEAD
to capture changes. Collect
git diff HEAD
for context.
Identify task intent from session history.
Detect convention files (AGENTS.md, CLAUDE.md, .cursorrules) — see
references/triage-protocol.md
.
For 6+ files: run triage per references/triage-protocol.md:
uv run scripts/project-scanner.py [path]
for project profile
Git history analysis (hot files, recent changes, related issues)
Risk-stratify all changed files (HIGH/MEDIUM/LOW)
Determine specialist triggers (security, observability, requirements)
Detect monorepo workspaces and scope reviewers per package
For 1-5 files: lightweight triage — classify risk levels and run content type detection; do not skip full team composition. (Note: always-maximum-depth applies to team effort; triage for small reviews can still skip git history analysis steps to save time.)
Session Step 2: Scale and Launch (Wave 1)
Scope
Strategy
Any scope
Content-adaptive team (see below). Always maximum depth. No inline-only mode.
Content-adaptive team composition:
Always spawn:
Correctness Reviewer → Passes A/B/C
Design Reviewer → Passes A/B/C
Efficiency Reviewer → Passes A/B/C
Code Reuse Reviewer → Passes A/B/C
Test Quality Reviewer → Passes A/B/C (always spawns — scope depends on what's present — see template)
Spawn when triggered by triage content detection:
Security Specialist → when auth/payments/crypto/user-data/external-I/O code present
Observability Specialist → when service/API/long-running process code present
Requirements Validator → when spec auto-detected (PR description, linked issues, SPEC.md, docs/, commit messages)
Data Migration Specialist → when schema change files present
Frontend Specialist → when UI/component files (tsx, jsx, css, vue) present
[Lead: triage (Wave 0), Judge reconciliation (Wave 3), final report]
|-- Correctness Reviewer → Passes A/B/C
|-- Design Reviewer → Passes A/B/C
|-- Efficiency Reviewer → Passes A/B/C
|-- Code Reuse Reviewer → Passes A/B/C
|-- Test Quality Reviewer → Passes A/B/C
|-- [Security Specialist if triage triggers]
|-- [Observability Specialist if triage triggers]
|-- [Requirements Validator if spec auto-detected]
|-- [Data Migration Specialist if schema changes present]
|-- [Frontend Specialist if UI/component files present]
Each reviewer runs 3 internal passes (references/team-templates.md § Internal Pass Structure):
Pass A: quick scan all files (opus, 3-5 files per subagent)
Pass B: deep dive HIGH-risk flagged files (opus, 1 per file)
Pass C: research validate findings (batched per research-playbook.md)
Prompt templates: read references/team-templates.md
Session Step 3: Research Validate (Wave 2)
For inline/small reviews: lead collects all findings and dispatches validation wave.
For team reviews: each teammate handles validation internally (Pass C).
Batch findings by validation type. Dispatch order:
Slopsquatting detection (security-critical, opus)
HIGH-risk findings (2+ sources, sonnet)
MEDIUM-risk findings (1 source, opus)
Skip LOW-risk obvious issues
Batch sizing: 5-8 findings per subagent (optimal). See references/research-playbook.md § Batch Optimization.
Session Step 4: Judge Reconcile (Wave 3)
Run the 8-step Judge protocol (references/judge-protocol.md):
Normalize findings (scripts/finding-formatter.py assigns HR-S-{seq} IDs)
Cluster by root cause
Deduplicate within clusters
Confidence filter (≥0.7 report, 0.3-0.7 unconfirmed, <0.3 discard)
Resolve conflicts between contradicting findings
Check interactions (fixing A worsens B? fixing A fixes B?)
Elevate patterns in 3+ files to systemic findings
Rank by score = severity_weight × confidence × blast_radius
If 2+ findings survive, run self-verification (Wave 3.5): references/self-verification.md
Session Step 5: Present and Execute
Present all findings with evidence, confidence scores, and citations.
After presenting findings, ask: "Which findings should I create a fix plan for? [all / select by ID / skip]"
If approved: Generate an orchestration implementation plan for the selected findings using Pattern E (TeamCreate + nested subagent waves). No token budget caps. Create a TaskList entry per finding. Dispatch fixes in parallel where independent; sequential only when same-file edits conflict. Verify after all tasks complete (build, tests, behavior). See references/auto-fix-protocol.md for orchestration template.
Output format: read references/output-formats.md
For SARIF output: read references/sarif-output.md
Mode 2: Full Codebase Audit
Audit Step 1: Triage (Wave 0)
Full triage per references/triage-protocol.md:
uv run scripts/project-scanner.py [path]
for project profile
Git history analysis (3 parallel opus subagents: hot files, recent changes, related issues)
Risk-stratify all files (HIGH/MEDIUM/LOW)
Context assembly (project type, architecture, test coverage, PR history)
Determine specialist triggers for team composition
For 500+ files: prioritize HIGH-risk, recently modified, entry points, public API.
State scope limits in report.
Audit Step 2: Design and Launch Team (Wave 1)
Use triage results to select team composition. Apply the same content-adaptive team as Session Review.
Assign file ownership based on risk stratification — HIGH-risk files get domain reviewer + specialist coverage.
Scope
Strategy
Any scope
Content-adaptive team (see below). Always maximum depth. No inline-only mode.
Content-adaptive team composition:
Always spawn:
Correctness Reviewer → Passes A/B/C
Design Reviewer → Passes A/B/C
Efficiency Reviewer → Passes A/B/C
Code Reuse Reviewer → Passes A/B/C
Test Quality Reviewer → Passes A/B/C (always spawns — scope depends on what's present — see template)
Spawn when triggered by triage content detection:
Security Specialist → when auth/payments/crypto/user-data/external-I/O code present
Observability Specialist → when service/API/long-running process code present
Requirements Validator → when spec auto-detected (PR description, linked issues, SPEC.md, docs/, commit messages)
Data Migration Specialist → when schema change files present
Frontend Specialist → when UI/component files (tsx, jsx, css, vue) present
[Lead: triage (Wave 0), cross-domain analysis, Judge reconciliation (Wave 3), report]
|-- Correctness Reviewer → Passes A/B/C
|-- Design Reviewer → Passes A/B/C
|-- Efficiency Reviewer → Passes A/B/C
|-- Code Reuse Reviewer → Passes A/B/C
|-- Test Quality Reviewer → Passes A/B/C
|-- [Security Specialist if triage triggers]
|-- [Observability Specialist if triage triggers]
|-- [Requirements Validator if spec auto-detected]
|-- [Data Migration Specialist if schema changes present]
|-- [Frontend Specialist if UI/component files present]
Audit-only scoping for large codebases (500+ files):
the core reviewers (Correctness, Design, Efficiency) split file ownership by risk tier; Code Reuse Reviewer is scoped to changed/HIGH-risk files plus a sampled cross-section (top 50 files by fan-in and LOC) — not the entire codebase; Test Quality Reviewer focuses on test files that cover changed/HIGH-risk code. Lead continues to run cross-domain analysis in parallel (Audit Step 3 — unchanged). The 500+ file splitting rule does NOT apply in Session Review mode (which always operates on a bounded diff).
Each teammate runs 3 internal passes (references/team-templates.md § Internal Pass Structure).
Scaling: references/team-templates.md § Scaling Matrix.
Audit Step 3: Cross-Domain Analysis (Lead, parallel with Wave 1)
While teammates review, lead spawns parallel subagents for:
Architecture: module boundaries, dependency graph
Data flow: trace key paths end-to-end
Error propagation: consistency across system
Shared patterns: duplication vs. necessary abstraction
Audit Step 4: Research Validate (Wave 2)
Each teammate handles research validation internally (Pass C).
Lead validates cross-domain findings separately.
Batch optimization: references/research-playbook.md § Batch Optimization.
Audit Step 5: Judge Reconcile (Wave 3)
Collect all findings from all teammates + cross-domain analysis.
Run the 8-step Judge protocol (references/judge-protocol.md).
Cross-domain deduplication: findings spanning multiple domains → elevate to systemic.
Audit Step 6: Report
Output format: read references/output-formats.md
Required sections: Critical, Significant, Cross-Domain, Health Summary,
Top 3 Recommendations, Statistics. All findings include evidence + citations.
Audit Step 7: Execute (If Approved)
After presenting findings, ask: "Which findings should I create a fix plan for? [all / select by ID / skip]"
If approved: Generate an orchestration implementation plan for the selected findings using Pattern E (TeamCreate + nested subagent waves). No token budget caps. Create a TaskList entry per finding. Dispatch fixes in parallel where independent; sequential only when same-file edits conflict. Verify after all tasks complete (build, tests, behavior). See references/auto-fix-protocol.md for orchestration template.
Reference Files
Load ONE reference at a time. Do not preload all references into context.
File
When to Read
~Tokens
references/triage-protocol.md
During Wave 0 triage (both modes)
1500
references/checklists.md
During analysis or building teammate prompts
2800
references/research-playbook.md
When setting up research validation (Wave 2)
2200
references/judge-protocol.md
During Judge reconciliation (Wave 3)
1200
references/self-verification.md
After Judge (Wave 3.5) — adversarial false-positive reduction
900
references/auto-fix-protocol.md
When implementing fixes after approval
800
references/output-formats.md
When producing final output
1100
references/sarif-output.md
When outputting SARIF format for CI tooling
700
references/supply-chain-security.md
When reviewing dependency security
1000
references/team-templates.md
When designing teams (Mode 2 or large Mode 1)
2200
references/review-lenses.md
When applying creative review lenses
1600
references/ci-integration.md
When running in CI pipelines
700
references/conventional-comments.md
When producing PR comments or CI annotations
400
references/dependency-context.md
During Wave 0 triage for cross-file dependency analysis
500
Script
When to Run
scripts/project-scanner.py
Wave 0 triage — deterministic project profiling
scripts/finding-formatter.py
Wave 3 Judge — normalize findings to structured JSON (supports --format sarif)
scripts/review-store.py
Save, load, list, diff review history
scripts/sarif-uploader.py
Upload SARIF results to GitHub Code Scanning
scripts/learnings-store.py
Manage false-positive learnings (add, check, list, clear)
Template
When to Render
templates/dashboard.html
After Judge reconciliation — inject findings JSON into data tag
Critical Rules
Never skip triage (Wave 0) — risk classification informs everything downstream
Every non-trivial finding must have research evidence or be discarded
Confidence < 0.3 = discard (except P0/S0 — report as unconfirmed)
Do not police style preferences — follow the codebase's conventions. Exception: violations of agent behavior rules in AGENTS.md/CLAUDE.md (toolchain, auth, secrets, safety-critical directives) are findings at the Convention Violations tier severity. Pure style rules (formatting, naming) are never policed.
Do not report phantom bugs requiring impossible conditions
More than 12 findings means re-prioritize — 5 validated findings beat 50 speculative
Never skip Judge reconciliation (Wave 3)
Always present before implementing (approval gate)
Always verify after implementing (build, tests, behavior)
Never assign overlapping file ownership
Maintain positive-to-constructive ratio of 3:1 — re-examine low-severity findings if ratio skews negative — except when 3+ P0/P1 findings are present, in which case report all critical findings without enforcing the ratio.
Acknowledge healthy codebases — if no P0/P1 or S0 findings, state this explicitly
Apply at least 2 creative lenses per review scope — Adversary is mandatory for security-sensitive code
Load ONE reference file at a time — do not preload all references into context
Review against the codebase's own conventions, not an ideal standard
Run self-verification (Wave 3.5) when 2+ findings survive Judge — skip for fewer findings or fully degraded mode
Follow auto-fix protocol for implementing fixes — never apply without diff preview and user confirmation
Check for convention files (AGENTS.md, CLAUDE.md, .cursorrules) during triage — validate code against project's declared rules
Every finding must include a reasoning chain (WHY) before the finding statement (WHAT)
Every finding must include a citation anchor
[file:start-end]
mechanically verified against source
Check learnings store during Judge Wave 3 Step 4 — suppress findings matching stored false-positive dismissals
Code Reuse Reviewer runs on every review scope — always cite file:line for existing equivalents.
Fact evidence (Grep) is sufficient for reuse and simplification findings; no WebSearch required unless confirming why the pattern is harmful.
No inline-only review — always spawn the full content-adaptive team regardless of file count.
Test Quality Reviewer always spawns — when test files are in scope: full 4-dimension review; when no test files in scope: coverage gap search (Grep for any tests covering changed functions; flag untested code as a finding).
Violations of AGENTS.md/CLAUDE.md
agent behavior rules
(toolchain, auth, secrets, safety) are reported as findings — severity per the Convention Violations tier in checklists.md. Style-only preferences (formatting, naming) are still not policed per Rule 4.
Post-approval execution generates an orchestration plan (Pattern E) — never apply fixes sequentially; parallelize all independent changes.