| name | phased-code-review |
|---|---|
| description | Systematic, resumable, multi-phase deep review of a large or multi-component codebase (thousands of files; Windows services, RPC/IPC, daemons, libraries, external integrations) to dig out technical, logical, security, concurrency, lifecycle, resource-leak and cross-file bugs — engineered so token/session limits never lose progress. Use when the user wants to audit or review an entire codebase or a large subsystem in phases, "dig out bugs" across many files, do a comprehensive multi-pass review, or continue such a review after an interruption. Also use when the user references REVIEW_PLAYBOOK or asks to review "in phases/parts". |
Phased, resumable deep code review
The full method with prompt templates, JSON schemas, and gotchas is in REVIEW_PLAYBOOK.md bundled next to this file — read it before starting a real run.
Core principle (why this survives token limits)
Disk is the source of truth; context is disposable. Every intermediate result is a durable artifact on disk, and every phase is independently resumable. If a token/session limit cuts you off anywhere, the next session reads the artifacts and continues. Never drag large data through the conversation; the orchestrator launches agents and parses their JSON with scripts, but never ingests full file dumps.
The 10 phases (each ends in an on-disk checkpoint)
- Setup & inventory — script-list every source file with line counts →
00_inventory.json. - Cluster — group files by subsystem/component into ~15–60 clusters (~5–10 files each); add an
integration-spinecluster for cross-file flows →01_clusters.json. - Known baseline — condense already-known issues to one line each →
02_known.md(grows every pass; injected into every agent so nothing is re-reported). - Fan-out review — Workflow
pipeline(); one agent per cluster with aschema; run in waves of ~15–20;resumeFromRunIdon interruption →03_candidates.json. - Adversarial verify — one skeptical verifier per candidate; keep only
is_real && is_new→04_verified.json(+04_rejected.json). Removes ~25% false/dup. - Consolidate — Python merges dups, routes by category, sorts, assigns IDs continuing existing numbering →
05_plan.json+ a one-line-per-finding digest. - Draft prose — one agent per group writes its own
out_X.md(writes from verified findings, does not re-read code). Fallback mandatory: validate which groups are complete; write missing ones yourself. - Splice into docs — back up first; script with anchor-assert exactly once; re-read before write; preserve format; validate after.
- Deliverables (optional) — generate PDFs/zip into scratch then copy over; verify textually.
- Handoff — update
HANDOFF.mdadditively; append new findings to02_known.md.
Structured-output schemas (always pass these to agents)
Findings (review agent):
{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object",
"properties":{"title":{"type":"string"},"file":{"type":"string"},"line":{"type":"integer"},
"severity":{"enum":["critical","high","medium","low"]},
"category":{"enum":["technical","logical","security","concurrency","lifecycle","resource-leak","error-handling","cross-file"]},
"description":{"type":"string"},"failure_scenario":{"type":"string"},"cross_file":{"type":"string"}},
"required":["title","file","line","severity","category","description","failure_scenario"]}}},"required":["findings"]}
Verdict (verify agent):
{"type":"object","properties":{"is_real":{"type":"boolean"},"is_new":{"type":"boolean"},
"confidence":{"enum":["high","medium","low"]},"corrected_severity":{"enum":["critical","high","medium","low"]},
"corrected_line":{"type":"integer"},"dup_of":{"type":"string"},"reasoning":{"type":"string"}},
"required":["is_real","is_new","confidence","reasoning"]}
Resume protocol (when cut off)
- Read
HANDOFF.md+MANIFEST.md. 2. Find the first unfinished artifact (00→09). 3. Workflow phase:resumeFromRunId. 4. Draft phase: validate missingout_*.md, finish them yourself. 5. Continue.
Non-negotiable rules
- Agent-free fallback is mandatory — helper agents can die on token limits; each writes a separate file so partial work survives, and the main loop must be able to finish alone.
- Re-read before writing any doc — expect concurrent edits; reconcile ID collisions by taking the next free number; keep handoff edits additive.
- Scripts for everything deterministic (merge/number/splice/tables); agents only for judgment (find + verify).
- Anchor-assert "exactly once" before every scripted splice; back up docs first.
- Checkpoint to disk after every non-trivial step — assume you could be cut off right after any tool action.
See REVIEW_PLAYBOOK.md (bundled) for the full phase detail, prompt templates, scaling guidance, and the Windows/PDF gotchas.