Claude-Code-Workflow/.claude/commands/workflow/review-fix.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
review-fix	Automated fixing of code review findings with AI-powered planning and coordinated execution. Uses intelligent grouping, multi-stage timeline coordination, and test-driven verification.	<export-file|review-dir> [--resume] [--max-iterations=N]	SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*), Edit(*), Write(*)

Workflow Review-Fix Command

Quick Start

# Fix from exported findings file
/workflow:review-fix .workflow/.reviews/session-WFS-123/fix-export-1706184622000.json

# Fix from review directory (auto-discovers latest export)
/workflow:review-fix .workflow/.reviews/session-WFS-123/

# Resume interrupted fix session
/workflow:review-fix --resume

# Custom max retry attempts per finding
/workflow:review-fix .workflow/.reviews/session-WFS-123/ --max-iterations=5

Fix Source: Exported findings from review cycle dashboard Output Directory: {review-dir}/fixes/{fix-session-id}/ (fixed location) Default Max Iterations: 3 (per finding, adjustable) CLI Tools: @cli-planning-agent (planning), @cli-execute-agent (fixing)

What & Why

Core Concept

Automated fix orchestrator with two-phase architecture: AI-powered planning followed by coordinated parallel/serial execution. Generates fix timeline with intelligent grouping and dependency analysis, then executes fixes with conservative test verification.

Fix Process:

• Planning Phase: AI analyzes findings, generates fix plan with grouping and execution strategy
• Execution Phase: Main orchestrator coordinates agents per timeline stages
• No rigid structure: Adapts to task requirements, not bound to fixed JSON format

vs Manual Fixing:

• Manual: Developer reviews findings one-by-one, fixes sequentially
• Automated: AI groups related issues, executes in optimal parallel/serial order with automatic test verification

Value Proposition

1. Intelligent Planning: AI-powered analysis identifies optimal grouping and execution strategy
2. Multi-stage Coordination: Supports complex parallel + serial execution with dependency management
3. Conservative Safety: Mandatory test verification with automatic rollback on failure
4. Real-time Visibility: Dashboard shows planning progress, stage timeline, and active agents
5. Resume Support: Checkpoint-based recovery for interrupted sessions

Orchestrator Boundary (CRITICAL)

• ONLY command for automated review finding fixes
• Manages: Planning phase coordination, stage-based execution, agent scheduling, progress tracking
• Delegates: Fix planning to @cli-planning-agent, fix execution to @cli-execute-agent

Execution Flow

1. Discovery & Initialization
   └─ Validate export file, create fix session structure, initialize state files → Update dashboard

2. Phase 2: Planning (@cli-planning-agent):
   ├─ Analyze findings for patterns and dependencies
   ├─ Group by file + dimension + root cause similarity
   ├─ Determine execution strategy (parallel/serial/hybrid)
   ├─ Generate fix timeline with stages
   └─ Output: fix-plan.json → Update dashboard to execution phase

3. Phase 3: Execution (Stage-based):
   For each timeline stage:
   ├─ Load groups for this stage
   ├─ If parallel: Launch all group agents simultaneously
   ├─ If serial: Execute groups sequentially
   ├─ Each agent:
   │  ├─ Analyze code context
   │  ├─ Apply fix per strategy
   │  ├─ Run affected tests
   │  ├─ On test failure: Rollback, retry up to max_iterations
   │  └─ On success: Commit, write completion JSON
   ├─ Update fix-progress.json after each finding
   └─ Advance to next stage

4. Phase 4: Completion
   └─ Aggregate results → Generate fix-summary.md → Update history → Output summary

Agent Roles

Agent	Responsibility
Orchestrator	Input validation, session management, planning coordination, stage-based execution scheduling, progress tracking, aggregation
@cli-planning-agent	Findings analysis, intelligent grouping (file+dimension+root cause), execution strategy determination (parallel/serial/hybrid), timeline generation with dependency mapping
@cli-execute-agent	Fix execution per group, code context analysis, Edit tool operations, test verification, git rollback on failure, completion JSON generation

Enhanced Features

1. Two-Phase Architecture

Phase Separation:

Phase	Agent	Output	Purpose
Planning	@cli-planning-agent	fix-plan.json	Analyze findings, group intelligently, determine optimal execution strategy
Execution	@cli-execute-agent	completions/*.json	Execute fixes per plan with test verification and rollback

Benefits:

• Clear separation of concerns (analysis vs execution)
• Reusable plans (can re-execute without re-planning)
• Better error isolation (planning failures vs execution failures)

2. Intelligent Grouping Strategy

Three-Level Grouping:

// Level 1: Primary grouping by file + dimension
{file: "auth.ts", dimension: "security"} → Group A
{file: "auth.ts", dimension: "quality"} → Group B
{file: "query-builder.ts", dimension: "security"} → Group C

// Level 2: Secondary grouping by root cause similarity
Group A findings → Semantic similarity analysis (threshold 0.7)
  → Sub-group A1: "missing-input-validation" (findings 1, 2)
  → Sub-group A2: "insecure-crypto" (finding 3)

// Level 3: Dependency analysis
Sub-group A1 creates validation utilities
Sub-group C4 depends on those utilities
→ A1 must execute before C4 (serial stage dependency)

Similarity Computation:

• Combine: description + recommendation + category
• Vectorize: TF-IDF or LLM embedding
• Cluster: Greedy algorithm with cosine similarity > 0.7

3. Execution Strategy Determination

Strategy Types:

Strategy	When to Use	Stage Structure
Parallel	All groups independent, different files	Single stage, all groups in parallel
Serial	Strong dependencies, shared resources	Multiple stages, one group per stage
Hybrid	Mixed dependencies	Multiple stages, parallel within stages

Dependency Detection:

• Shared file modifications
• Utility creation + usage patterns
• Test dependency chains
• Risk level clustering (high-risk groups isolated)

4. Conservative Test Verification

Test Strategy (per fix):

// 1. Identify affected tests
const testPattern = identifyTestPattern(finding.file);
// e.g., "tests/auth/**/*.test.*" for src/auth/service.ts

// 2. Run tests
const result = await runTests(testPattern);

// 3. Evaluate
if (result.passRate < 100%) {
  // Rollback
  await gitCheckout(finding.file);

  // Retry with failure context
  if (attempts < maxIterations) {
    const fixContext = analyzeFailure(result.stderr);
    regenerateFix(finding, fixContext);
    retry();
  } else {
    markFailed(finding.id);
  }
} else {
  // Commit
  await gitCommit(`Fix: ${finding.title} [${finding.id}]`);
  markFixed(finding.id);
}

Pass Criteria: 100% test pass rate (no partial fixes)

Core Responsibilities

Orchestrator

Phase 1: Discovery & Initialization

• Input validation: Check export file exists and is valid JSON
• Auto-discovery: If review-dir provided, find latest *-fix-export.json
• Session creation: Generate fix-session-id (fix-{timestamp})
• Directory structure: Create {review-dir}/fixes/{fix-session-id}/ with subdirectories
• State files: Initialize fix-state.json, fix-progress.json, active-fix-session.json
• TodoWrite initialization: Set up 4-phase tracking

Phase 2: Planning Coordination

• Launch @cli-planning-agent with findings data and project context
• Monitor planning progress (dashboard shows "Planning fixes..." indicator)
• Validate fix-plan.json output (schema conformance)
• Load plan into memory for execution phase
• Update fix-state.json with plan_file reference
• TodoWrite update: Mark planning complete, start execution

Phase 3: Execution Orchestration

• Load fix-plan.json timeline stages
• For each stage:
  • If parallel mode: Launch all group agents via Promise.all()
  • If serial mode: Execute groups sequentially with await
  • Assign agent IDs (agents update their fix-progress-{N}.json)
• Handle agent failures gracefully (mark group as failed, continue)
• Advance to next stage only when current stage complete
• Dashboard polls and aggregates fix-progress-{N}.json files for display

Phase 4: Completion & Aggregation

• Collect final status from all fix-progress-{N}.json files
• Generate fix-summary.md with timeline and results
• Update fix-history.json with new session entry
• Remove active-fix-session.json
• TodoWrite completion: Mark all phases done
• Output summary to user with dashboard link

Planning Agent (@cli-planning-agent)

Role: Analyze findings, create execution strategy, initialize progress tracking

Orchestrator Provides:

• Review findings data (id, title, severity, file, description, recommendations)
• Project context (structure, test framework, git status)
• Output directory and template paths

Agent Outputs:

• fix-plan.json (groups, timeline, execution strategy)
• fix-progress-{N}.json (one per group, initial state)

Execution Agent (@cli-execute-agent)

Role: Execute fixes for assigned group, update progress in real-time

Orchestrator Provides:

• Group assignment (from fix-plan.json)
• Fix strategy and risk assessment (from fix-plan.json)
• Progress file path (fix-progress-{N}.json)

Agent Responsibilities:

• Read/update assigned progress file
• Apply fixes with flow control tracking
• Run tests and verify
• Commit successful fixes to git

Reference

CLI Tool Configuration

Planning Agent:

{
  subagent_type: "cli-planning-agent",
  timeout: 300000, // 5 minutes for planning
  description: "Generate fix plan for N code review findings"
}

Execution Agent:

{
  subagent_type: "cli-execute-agent",
  timeout: 3600000, // 60 minutes per group (adjustable)
  description: "Fix M issues: {group_name}"
}

Output File Structure

.workflow/.reviews/{review-id}/
├── fix-export-{timestamp}.json     # Exported findings (input)
└── fixes/{fix-session-id}/
    ├── fix-plan.json               # Planning agent output (execution plan)
    ├── fix-progress-1.json         # Group 1 progress (planning agent init → agent updates)
    ├── fix-progress-2.json         # Group 2 progress (planning agent init → agent updates)
    ├── fix-progress-3.json         # Group 3 progress (planning agent init → agent updates)
    ├── fix-summary.md              # Final report (orchestrator generates)
    ├── active-fix-session.json     # Active session marker
    └── fix-history.json            # All sessions history

File Producers:

• Planning Agent: fix-plan.json, all fix-progress-*.json (initial state)
• Execution Agents: Update assigned fix-progress-{N}.json in real-time
• Dashboard: Reads fix-plan.json + all fix-progress-*.json, aggregates in-memory every 3 seconds

Agent Output Files

fix-plan.json:

• Generated by: @cli-planning-agent
• Template: ~/.claude/workflows/cli-templates/fix-plan-template.json
• Purpose: Execution strategy, group definitions, timeline stages
• Orchestrator uses: Load groups, determine execution order, assign agents

fix-progress-{N}.json (one per group):

• Generated by: @cli-planning-agent (initial) → @cli-execute-agent (updates)
• Template: ~/.claude/workflows/cli-templates/fix-progress-template.json
• Purpose: Track individual group progress with flow control steps
• Consumed by: Dashboard (reads all, aggregates in-memory)

Agent Invocation Template

Planning Agent:

Task({
  subagent_type: "cli-planning-agent",
  description: `Generate fix plan and initialize progress files for ${findings.length} findings`,
  prompt: `
    Analyze ${findings.length} code review findings and generate:
    - fix-plan.json (execution strategy, groups, timeline)
    - fix-progress-{N}.json for each group (initial state)

    Input: ${JSON.stringify(findings, null, 2)}
    Templates: @~/.claude/workflows/cli-templates/fix-plan-template.json
              @~/.claude/workflows/cli-templates/fix-progress-template.json
    Output Dir: ${sessionDir}
  `
})

Execution Agent (per group):

Task({
  subagent_type: "cli-execute-agent",
  description: `Fix ${group.findings.length} issues: ${group.group_name}`,
  prompt: `
    Execute fixes for findings in ${group.progress_file}.
    Read initial state, apply fixes, run tests, commit changes.
    Update progress file in real-time with flow_control steps.

    Group: ${group.group_id} (${group.group_name})
    Progress File: ${group.progress_file}
    Fix Strategy: ${JSON.stringify(group.fix_strategy, null, 2)}
  `
})

Completion Conditions

Success Criteria:

• ✅ All findings processed (fixed or failed)
• ✅ Success rate ≥ 70% (configurable threshold)
• ✅ All fixed code has passing tests
• ✅ All changes committed to git
• ✅ All fix-progress-{N}.json files have status = "completed"
• ✅ fix-summary.md generated
• ✅ fix-history.json updated

Trigger Next Phase:

• Planning complete → Start execution
• Stage complete → Advance to next stage
• All stages complete → Generate completion report

Error Handling

Planning Failures:

• Invalid template → Abort with error message
• Insufficient findings data → Request complete export
• Planning timeout → Retry once, then fail gracefully

Execution Failures:

• Agent crash → Mark group as failed, continue with other groups
• Test command not found → Skip test verification, warn user
• Git operations fail → Abort with error, preserve state

Rollback Scenarios:

• Test failure after fix → Automatic git checkout rollback
• Max iterations reached → Leave file unchanged, mark as failed
• Unrecoverable error → Rollback entire group, save checkpoint

TodoWrite Structure

Initialization:

TodoWrite({
  todos: [
    {content: "Phase 1: Discovery & Initialization", status: "completed"},
    {content: "Phase 2: Planning", status: "in_progress"},
    {content: "Phase 3: Execution", status: "pending"},
    {content: "Phase 4: Completion", status: "pending"}
  ]
});

During Execution:

TodoWrite({
  todos: [
    {content: "Phase 1: Discovery & Initialization", status: "completed"},
    {content: "Phase 2: Planning", status: "completed"},
    {content: "Phase 3: Execution", status: "in_progress"},
    {content: "  → Stage 1: Parallel execution (3 groups)", status: "completed"},
    {content: "    • Group G1: Auth validation (2 findings)", status: "completed"},
    {content: "    • Group G2: Query security (3 findings)", status: "completed"},
    {content: "    • Group G3: Config quality (1 finding)", status: "completed"},
    {content: "  → Stage 2: Serial execution (1 group)", status: "in_progress"},
    {content: "    • Group G4: Dependent fixes (2 findings)", status: "in_progress"},
    {content: "Phase 4: Completion", status: "pending"}
  ]
});

Update Rules:

• Add stage items dynamically based on fix-plan.json timeline
• Add group items per stage
• Mark completed immediately after each group finishes
• Update parent phase status when all child items complete

Best Practices

1. Trust AI Planning: Planning agent's grouping and execution strategy are based on dependency analysis
2. Conservative Approach: Test verification is mandatory - no fixes kept without passing tests
3. Parallel Efficiency: Default 3 concurrent agents balances speed and resource usage
4. Monitor Dashboard: Real-time stage timeline and agent status provide execution visibility
5. Resume Support: Fix sessions can resume from checkpoints after interruption
6. Manual Review: Always review failed fixes manually - may require architectural changes
7. Incremental Fixing: Start with small batches (5-10 findings) before large-scale fixes