Deep Agent Review

Deep Agent Review

Orchestrate exhaustive multi-agent code reviews with progressive findings, verified claims, and actionable remediation plans.

Core Principle

One approval at start, then complete autonomous execution with verified findings.

YOU ARE THE ORCHESTRATOR: You coordinate review phases by dispatching specialized subagents. You never write findings yourself - you manage the review process.

What Makes This Different

Execution Model

START
  │
  ▼
1. EXPLORER: Map codebase into semantic areas
   └─ Output: review/areas.yaml
  │
  ▼
2. USER APPROVAL: Review and approve areas
  │
  ▼
3. SPECIALISTS: Deep review each area (parallel)
   ├─ Save findings incrementally to review/[area].yaml
   └─ Classify: type, severity, file:line, fix plan
  │
  ▼
4. VERIFIERS: Verify all claims by severity
   ├─ Critical verifier → plans/review/critical-verified.yaml
   ├─ High verifier → plans/review/high-verified.yaml
   └─ Medium/Low verifier → plans/review/standard-verified.yaml
  │
  ▼
5. MASTER PLANS: Generate remediation roadmaps
   └─ Output: plans/review/master-plan.yaml
  │
  ▼
REPORT: Summary with statistics

Quick Start

1. Initialize Review

Initialize deep agent review for this codebase.

You will:

• Dispatch an Explorer agent to map semantic areas
• Create review/areas.yaml with area definitions

2. Approve Areas

Review review/areas.yaml and confirm:

• Areas cover all important code
• Specializations are appropriate
• No blind spots

3. Execute Review

Once approved:

Execute the review.

All phases run automatically without further interaction.

Phase Details

Phase 1: Exploration

Goal: Map codebase into semantic areas, not generic layers.

Explorer prompt template:

ROLE: Codebase Explorer
MISSION: Map this codebase into semantic areas for deep review.

REQUIREMENTS:
- Go beyond "backend/frontend/database"
- Identify domain-specific areas (auth, payments, game-lifecycle, etc.)
- Understand HOW things work, not just WHERE they are
- Identify cross-cutting concerns
- Note any incomplete/broken features

OUTPUT: Create review/areas.yaml with:

areas:
  - name: "[semantic name]"
    description: "[what this area does and why it matters]"
    paths: ["glob/patterns/**"]
    focus: ["specific concerns for this area"]
    specialist: "[recommended agent type]"
    
cross_cutting:
  - name: "[concern name]"
    affects: ["area names"]
    
broken_incomplete:
  - feature: "[name]"
    evidence: "[what's missing/broken]"
    impact: "[user/business impact]"

SPECIALIST MAPPING:
- Security concerns → code-reviewer or general with security focus
- Frontend/UI → frontend-developer
- Backend/API → backend-security-coder
- Architecture → architect-review
- DevOps/Infra → devops-troubleshooter
- General exploration → explore agent

Save to: review/areas.yaml

Semantic area examples:

• auth-flow - Authentication, session management, tokens
• game-lifecycle - Game creation, publishing, state transitions
• leaderboard-system - Scoring, ranking, display
• admin-controls - Admin features, permissions, management
• user-data - User profiles, preferences, privacy
• api-surface - All endpoints, validation, responses
• data-layer - Schema, queries, migrations, caching

Phase 2: Specialist Review

Goal: Deep dive into each area with progressive findings.

Specialist prompt template:

ROLE: [Area] Specialist
AREA: [area name]
MISSION: Conduct exhaustive review of [area name].

SCOPE:
- Paths: [glob patterns]
- Focus: [specific concerns]

FINDINGS FORMAT:
Save findings incrementally to review/[area-name].yaml

findings:
  - id: "[area]-[number]"
    type: "[security|quality|performance|correctness|maintainability|accessibility]"
    severity: "[critical|high|medium|low|nitpick]"
    title: "[brief description]"
    file: "[path]"
    line: [line number or range]
    description: |
      [detailed explanation of the issue]
    evidence: |
      [code snippet or behavior description]
    impact: |
      [what happens if not fixed]
    fix:
      approach: "[high-level fix strategy]"
      steps:
        - "[step 1]"
        - "[step 2]"
      effort: "[low|medium|high]"
    references:
      - "[URL or doc reference]"

REVIEW APPROACH:
1. Start with high-level understanding (read key files)
2. Find obvious issues, save immediately
3. Go deeper into edge cases, save incrementally
4. Check cross-cutting concerns (security, perf, etc.)
5. Review error handling and edge cases
6. Look for missing/incomplete features
7. Final pass for anything missed

SEVERITY GUIDELINES:
- CRITICAL: Security breach, data loss, system down
- HIGH: Feature broken, security risk, major perf issue
- MEDIUM: Feature degraded, quality issue, minor security concern
- LOW: Code smell, minor bug with workaround
- NITPICK: Style, minor improvement

TYPE GUIDELINES:
- security: Auth, injection, exposure, permissions
- quality: Code structure, patterns, duplication
- performance: Speed, memory, scalability
- correctness: Logic errors, wrong behavior
- maintainability: Documentation, complexity, tests
- accessibility: A11y compliance, screen readers

SAVE PROGRESSIVELY:
- Don't wait until end to save findings
- Save after each major discovery
- Update file as you find more
- This allows parallel progress tracking

Save to: review/[area-name].yaml

Phase 3: Verification

Goal: Verify all claims before finalizing.

Critical/High verifier template:

ROLE: [Severity] Verifier
MISSION: Verify all [critical/high] severity findings are accurate.

INPUT FILES:
- review/*.yaml (all area findings)

VERIFICATION PROCESS:
For each [critical/high] finding:
1. Read the referenced file and line
2. Confirm the issue exists as described
3. Verify the severity is appropriate
4. Validate the fix approach is viable
5. Check for additional context that changes assessment

OUTPUT FORMAT:
Save to: plans/review/[severity]-verified.yaml

verified:
  - id: "[original finding id]"
    status: "[confirmed|adjusted|rejected]"
    adjusted_severity: "[if changed]"
    notes: "[verification notes]"
    additional_context: "[any new information]"

rejected:
  - id: "[original finding id]"
    reason: "[why this finding is incorrect]"
    explanation: "[what's actually happening]"

RULES:
- Be skeptical - verify don't trust
- Read actual code, don't assume
- If severity is wrong, adjust it
- If finding is wrong, reject with explanation
- If more context needed, note it

Save to: plans/review/[severity]-verified.yaml

Standard verifier (medium/low/nitpick):

ROLE: Standard Verifier
MISSION: Verify medium, low, and nitpick severity findings.

[Same process as above but for lower severities]

Save to: plans/review/standard-verified.yaml

Phase 4: Master Plan Generation

Goal: Create actionable remediation roadmap.

Planner template:

ROLE: Remediation Planner
MISSION: Create master remediation plan from verified findings.

INPUTS:
- plans/review/critical-verified.yaml
- plans/review/high-verified.yaml
- plans/review/standard-verified.yaml

OUTPUT: plans/review/master-plan.yaml

structure:
meta:
  generated: "[timestamp]"
  total_findings: [count]
  by_severity:
    critical: [count]
    high: [count]
    medium: [count]
    low: [count]
    nitpick: [count]
  by_type:
    [type]: [count]

remediation:
  immediate:  # Critical issues
    - id: "[finding id]"
      title: "[brief title]"
      files: ["[affected files]"]
      effort: "[estimated effort]"
      dependencies: ["[blocking issues]"]
      
  short_term:  # High issues
    - id: "[finding id]"
      title: "[brief title]"
      files: ["[affected files]"]
      effort: "[estimated effort]"
      
  medium_term:  # Medium issues
    - id: "[finding id]"
      title: "[brief title]"
      files: ["[affected files]"]
      effort: "[estimated effort]"
      
  backlog:  # Low and nitpick
    - id: "[finding id]"
      title: "[brief title]"

execution_order:
  - phase: 1
    focus: "[what to fix]"
    findings: ["[ids]"]
    estimated_effort: "[total]"
  - phase: 2
    focus: "[what to fix]"
    findings: ["[ids]"]
    estimated_effort: "[total]"

Save to: plans/review/master-plan.yaml

File Structure

review/
├── areas.yaml           # Phase 1: Area definitions
├── auth-flow.yaml       # Phase 2: Area findings
├── game-lifecycle.yaml
├── leaderboard.yaml
└── ...

plans/review/
├── critical-verified.yaml   # Phase 3: Verified critical
├── high-verified.yaml       # Phase 3: Verified high
├── standard-verified.yaml   # Phase 3: Verified medium/low
└── master-plan.yaml         # Phase 4: Remediation roadmap

Dispatching Agents

Parallel Dispatch (Specialists)

// Dispatch all area specialists simultaneously
areas.forEach(area => {
  dispatchAgent({
    type: area.specialist, // code-reviewer, frontend-developer, etc.
    prompt: specialistPrompt(area),
    async: true
  });
});

// Wait for all to complete
await allComplete();

// Verify all review/*.yaml files exist

Sequential Dispatch (Verification)

// Verify in severity order
await dispatchAgent({
  type: 'code-reviewer',
  prompt: criticalVerifierPrompt()
});

await dispatchAgent({
  type: 'code-reviewer', 
  prompt: highVerifierPrompt()
});

await dispatchAgent({
  type: 'code-reviewer',
  prompt: standardVerifierPrompt()
});

// Generate master plan
await dispatchAgent({
  type: 'architect-review',
  prompt: plannerPrompt()
});

Severity Classification

Type Classification

Critical Rules

Rule 1: Progressive Saving

Specialists MUST save findings incrementally, not at the end.

• Find something → Save immediately
• Find more → Append/update
• This enables progress tracking and recovery

Rule 2: Verified Claims

No finding appears in final report without verification.

• Verifiers read actual code
• Verifiers confirm or reject claims
• Only verified findings go to master plan

Rule 3: Orchestrator Doesn't Review

You coordinate, you don't review.

• Dispatch specialists
• Collect their outputs
• Dispatch verifiers
• Generate reports
• Never write findings yourself

Rule 4: Semantic Areas

Areas reflect domain, not architecture.

• "game-lifecycle" not "backend"
• "auth-flow" not "database"
• Understand HOW things work

Rule 5: Actionable Plans

Every finding has a fix plan.

• Approach described
• Steps outlined
• Effort estimated

Progress Reporting

During Review (Optional)

Progress: [N]/[M] areas complete
Current: [area name]
Findings so far: [count] ([critical] critical, [high] high)

Final Report

# Deep Agent Review Complete

## Summary
- Areas reviewed: [N]
- Total findings: [N]
- Critical: [N]
- High: [N]
- Medium: [N]
- Low: [N]
- Nitpick: [N]

## Verification Status
- Critical findings: [N] verified, [N] adjusted, [N] rejected
- High findings: [N] verified, [N] adjusted, [N] rejected
- Standard findings: [N] verified, [N] adjusted, [N] rejected

## Immediate Actions Required
[List critical findings with file:line]

## Files
- Areas: review/areas.yaml
- Findings: review/*.yaml
- Verification: plans/review/*-verified.yaml
- Master Plan: plans/review/master-plan.yaml

Common Patterns

Pattern: Incomplete Features

When explorer identifies incomplete features:

broken_incomplete:
  - feature: "Game publishing"
    evidence: "Publish endpoint exists but never called, no tests"
    impact: "Users cannot publish games"

Create a specialist area for it:

areas:
  - name: "game-publishing"
    description: "Incomplete publishing feature"
    paths: ["**/publish*", "**/game*state*"]
    focus: ["Why incomplete?", "What's missing?", "Can it be fixed?"]

Pattern: Cross-Cutting Concerns

When multiple areas share concerns:

cross_cutting:
  - name: "Error handling"
    affects: ["auth-flow", "game-lifecycle", "api-surface"]

Instruct specialists to:

For cross-cutting concern "Error handling":
- Check how errors are handled in your area
- Note inconsistencies with other areas
- Identify missing error cases

Pattern: Area Dependencies

When areas interact:

areas:
  - name: "leaderboard"
    dependencies: ["game-lifecycle", "user-data"]
    focus: ["How does it get scores?", "What happens when game ends?"]

Integration with Other Skills

Use code-review skill for:

• Standard review checklist
• Security vulnerability patterns
• Performance anti-patterns

Use subagent-orchestration for:

• Implementation after review
• Multi-phase remediation

Use the-council for:

• Architectural decisions
• Complex trade-off analysis

Quick Reference

Minimal Review Setup

1. Explorer → review/areas.yaml
2. Approve areas
3. Specialists (parallel) → review/[area].yaml
4. Verifiers → plans/review/*-verified.yaml
5. Planner → plans/review/master-plan.yaml

Specialist Dispatch Template

You are the [Area] Specialist.
Review [paths] focusing on [concerns].
Save findings incrementally to review/[area].yaml.
Format: YAML with type, severity, file:line, fix plan.

Verifier Dispatch Template

You are the [Severity] Verifier.
Verify all [severity] findings in review/*.yaml.
Read actual code at file:line.
Save to plans/review/[severity]-verified.yaml.

Reference Documentation

• Finding Schema - Complete YAML schema for findings
• Area Examples - Semantic area patterns
• Specialist Profiles - Agent type mapping