review-to-disk

name	review-to-disk
description	Exhaustive multi-agent codebase review that writes all reports to docs/reviews/YYYY-MM-DD/. Each agent writes its own report to disk before returning, so reports survive context window limits. Use when you want a thorough review of src/ or any directory. Triggers include "review to disk", "exhaustive review", "full codebase review", or /review-to-disk.
argument-hint	[directory to review, default: src/]

Review to Disk

Multi-agent codebase review where every agent writes its report to a file on disk. This ensures reports survive context window limits.

Why This Exists

Background review agents produce large reports (10-30k chars each). When 8 agents run simultaneously, the orchestrator's context window fills up before it can read all results. Writing to disk means the work is never lost.

Workflow

Step 1: Setup

1. Determine the review target directory (default: src/)
2. Create output directory: docs/reviews/YYYY-MM-DD/
3. Read key files for context: package.json, README.md, CLAUDE.md, directory structure
4. Build a 2-3 sentence project description for agent prompts

Step 2: Launch Agents

Launch ALL agents in the background using the Task tool with run_in_background: true.

Critical instruction for each agent prompt: Every agent prompt MUST include this exact block (with the appropriate filename):

MANDATORY: Before returning your final response, you MUST write your complete report to:
  /path/to/docs/reviews/YYYY-MM-DD/{agent-name}.md

Use the Write tool to save your full report. This is non-negotiable — your report
must exist on disk even if the orchestrator never reads your return value.

Agent roster (adjust based on project type):

For TypeScript projects:

Agent Type	Filename	Focus
architecture-strategist	architecture-strategist.md	Module boundaries, layering, extension points, dependency flow
security-sentinel	security-sentinel.md	Code execution, trust bypass, path traversal, injection, OWASP
performance-oracle	performance-oracle.md	Hot paths, I/O patterns, startup time, algorithm complexity
pattern-recognition-specialist	pattern-recognition.md	Design patterns, anti-patterns, duplication, naming consistency
kieran-typescript-reviewer	kieran-typescript.md	Type safety, API design, error handling, code quality
code-simplicity-reviewer	code-simplicity.md	Over-engineering, YAGNI violations, dead code, unnecessary abstraction
data-integrity-guardian	data-integrity.md	File operations, database usage, transaction safety, data consistency
git-history-analyzer	git-history.md	Evolution patterns, churn hotspots, refactoring trajectory

For Rails projects, swap TypeScript-specific agents for:

• kieran-rails-reviewer
• dhh-rails-reviewer
• julik-frontend-races-reviewer (if Stimulus/JS present)
• data-migration-expert (if migrations present)

For Python projects:

• kieran-python-reviewer

Agent prompt template:

Review the ENTIRE {target_dir}/ directory of the {project_name} project — a {project_description}.

Your review focus: {agent_focus_description}

Review EVERY file in {target_dir}/. Read each one. Do not skip files or subdirectories.
Produce a comprehensive report with:
- Executive summary (2-3 sentences)
- Findings organized by severity (CRITICAL / HIGH / MEDIUM / LOW)
- Each finding: file path, line reference, description, impact, remediation
- Positive observations (things done well)
- Prioritized remediation roadmap

MANDATORY: Before returning your final response, you MUST write your complete report to:
  {output_dir}/{agent-name}.md

Use the Write tool to save your full report as a markdown file. This is non-negotiable —
your report must exist on disk even if the orchestrator never reads your return value.
The file must contain your COMPLETE report, not a summary.

Step 3: Monitor Progress

After launching all agents:

1. Report to the user which agents were launched
2. Periodically check agent status using TaskOutput with block: false
3. Report completions as they happen
4. When all agents complete, move to synthesis

Step 4: Synthesize

Once all agents have completed:

1. Read each report from docs/reviews/YYYY-MM-DD/
2. Do NOT read entire reports into context — use the Task tool to spawn a synthesis agent:

Task general-purpose:
"Read all review reports in docs/reviews/YYYY-MM-DD/ and produce a unified synthesis at
docs/reviews/YYYY-MM-DD/SYNTHESIS.md containing:
- Executive summary
- Cross-cutting themes (issues found by multiple agents)
- All findings deduplicated and sorted by severity
- Prioritized action plan
- Positive observations

Write the synthesis to docs/reviews/YYYY-MM-DD/SYNTHESIS.md using the Write tool."

3. After the synthesis agent completes, read just the SYNTHESIS.md and present a brief summary to the user

Step 5: Report

Present to the user:

• How many agents ran
• How many findings total (by severity)
• Top 3-5 most important findings
• Path to full reports: docs/reviews/YYYY-MM-DD/
• Offer to create beads/todos from findings

Key Design Decisions

• Agents write their own reports: The orchestrator never needs to receive or relay the full report content. This is the key insight that prevents context window blowout.
• Background execution: All agents run in background to avoid blocking and to maximize parallelism.
• Synthesis via sub-agent: Even the cross-report synthesis is done by a sub-agent writing to disk, keeping the orchestrator's context minimal.
• Date-stamped directories: Multiple reviews over time can coexist. Previous reviews are preserved.

Example Usage

/review-to-disk src/
/review-to-disk                    # defaults to src/
/review-to-disk src/commands/      # review specific subdirectory