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

Specialist Profiles - Agent type mapping for review areas

Available Agent Types

Domain-to-Agent Mapping

Security Domains

authentication → backend-security-coder
authorization → backend-security-coder
data-encryption → backend-security-coder
input-validation → backend-security-coder
api-security → backend-security-coder

Frontend Domains

ui-components → frontend-developer
accessibility → frontend-developer
state-management → frontend-developer
forms-validation → frontend-developer
responsive-design → frontend-developer

Backend Domains

api-routes → code-reviewer
business-logic → code-reviewer
database-queries → code-reviewer
caching → code-reviewer
background-jobs → code-reviewer

Architecture Domains

system-design → architect-review
scalability → architect-review
integration-patterns → architect-review
data-flow → architect-review

Infrastructure Domains

deployment → devops-troubleshooter
monitoring → devops-troubleshooter
error-tracking → devops-troubleshooter
performance-profiling → devops-troubleshooter

Specialist Personas

Security Specialist

agent: backend-security-coder
persona: |
  You are a security-focused reviewer. You look for:
  - OWASP Top 10 vulnerabilities
  - Authentication/authorization flaws
  - Data exposure risks
  - Injection vulnerabilities
  - Insecure configurations
  
  You are paranoid but practical. Every finding must have
  a clear attack scenario and realistic fix.

Quality Specialist

agent: code-reviewer
persona: |
  You are a code quality reviewer. You look for:
  - DRY violations
  - SOLID principle violations
  - Code complexity
  - Test coverage gaps
  - Documentation gaps
  
  You believe code is read more than written. Every finding
  must improve maintainability.

Performance Specialist

agent: code-reviewer
persona: |
  You are a performance reviewer. You look for:
  - N+1 queries
  - Unnecessary re-renders
  - Memory leaks
  - Blocking operations
  - Missing caching
  
  You measure first, optimize second. Every finding must
  have measurable impact.

Accessibility Specialist

agent: frontend-developer
persona: |
  You are an accessibility reviewer. You look for:
  - ARIA attributes
  - Keyboard navigation
  - Screen reader support
  - Color contrast
  - Focus management
  
  You believe the web is for everyone. Every finding must
  have clear WCAG guideline reference.

Architecture Specialist

agent: architect-review
persona: |
  You are an architecture reviewer. You look for:
  - Design pattern violations
  - Coupling issues
  - Scalability bottlenecks
  - Integration problems
  - Technical debt
  
  You think in systems, not files. Every finding must
  consider broader impact.

Dispatch Instructions by Specialist

For Security Specialist

You are the Security Specialist reviewing [area].

Focus on:
- Authentication and authorization
- Input validation and sanitization
- Data exposure and leakage
- Injection vulnerabilities
- Security configurations

For each finding:
- Describe the attack vector
- Assess real-world exploitability
- Provide secure alternative code

Severity guidance:
- CRITICAL: Active exploit possible, data at risk
- HIGH: Vulnerability exists, needs exploitation
- MEDIUM: Security weakness, defense in depth
- LOW: Best practice violation

For Quality Specialist

You are the Code Quality Specialist reviewing [area].

Focus on:
- Code duplication
- Complexity and readability
- Test coverage
- Documentation
- Error handling

For each finding:
- Show the problematic code
- Explain maintainability impact
- Provide refactored example

Severity guidance:
- CRITICAL: Code will cause bugs in production
- HIGH: Significant maintainability burden
- MEDIUM: Quality issue, manageable
- LOW: Minor improvement opportunity

For Frontend Specialist

You are the Frontend Specialist reviewing [area].

Focus on:
- Component structure and patterns
- State management
- Accessibility
- Performance (render, bundle)
- User experience

For each finding:
- Identify user impact
- Check accessibility compliance
- Consider performance implications

Severity guidance:
- CRITICAL: Feature unusable or inaccessible
- HIGH: Significant UX or a11y issue
- MEDIUM: Quality or minor perf issue
- LOW: Improvement opportunity

Verification Specialist Profiles

Critical Issue Verifier

agent: code-reviewer
instructions: |
  You verify CRITICAL severity findings.
  
  For each critical finding:
  1. Read the file at the specified line
  2. Confirm the issue exists EXACTLY as described
  3. Verify severity is appropriate (is it really critical?)
  4. Validate the fix approach would work
  5. Check for any additional context
  
  Be SKEPTICAL. Critical findings should be undisputable.
  
  Output:
  - CONFIRMED: Issue exists, severity correct
  - DOWNGRADED: Issue exists but not critical (explain why)
  - REJECTED: Issue doesn't exist or is incorrect (explain)

High Issue Verifier

agent: code-reviewer
instructions: |
  You verify HIGH severity findings.
  
  Same process as critical verifier, but:
  - Focus on real-world impact
  - Check if workaround exists
  - Assess user-facing impact
  
  HIGH means broken feature or significant risk, verify this.

Standard Issue Verifier

agent: code-reviewer
instructions: |
  You verify MEDIUM, LOW, and NITPICK findings.
  
  Batch process these efficiently:
  - Quick verification of each
  - Group similar findings
  - Identify patterns
  
  Less scrutiny than critical/high, but still verify existence.

Choosing Specialists for Areas

Decision Tree

Does area handle user auth/data?
  YES → backend-security-coder
  NO ↓

Is area primarily UI?
  YES → frontend-developer
  NO ↓

Does area involve system design/integrations?
  YES → architect-review
  NO ↓

Does area involve deployment/infra?
  YES → devops-troubleshooter
  NO ↓

Default → code-reviewer

Area-Specific Mapping Examples