Claude-Code-Workflow/ccw/docs-site/docs/commands/issue/issue-plan.md

title, sidebar_label, sidebar_position, description

title	sidebar_label	sidebar_position	description
issue:plan	issue:plan	3	Plan issue solutions with exploration and task breakdown

issue:plan

Batch plan issue resolution using intelligent agent-driven exploration and planning with failure-aware retry logic.

Description

The issue:plan command uses the issue-plan-agent to combine exploration and planning into a single closed-loop workflow. It generates executable solutions with task breakdowns, handles previous failure analysis, and supports batch processing of up to 3 issues per agent.

Key Features

• Explore + Plan: Combined workflow for faster planning
• Failure-aware: Analyzes previous failures to avoid repeats
• Batch processing: Groups semantically similar issues
• Auto-binding: Single solutions automatically bound
• Conflict detection: Identifies cross-issue file conflicts
• GitHub integration: Adds GitHub comment tasks when applicable

Usage

# Plan all pending issues (default)
/issue:plan

# Plan specific issues
/issue:plan GH-123,GH-124,GH-125

# Plan single issue
/issue:plan ISS-20251229-001

# Explicit all-pending
/issue:plan --all-pending

# Custom batch size
/issue:plan --batch-size 5

Arguments

Argument	Required	Description
issue-ids	No	Comma-separated issue IDs (default: all pending)
--all-pending	No	Explicit flag for all pending issues
--batch-size <n>	No	Max issues per batch (default: 3)
-y, --yes	No	Auto-bind without confirmation

Examples

Plan All Pending Issues

/issue:plan
# Output:
# Found 5 pending issues
# Processing 5 issues in 2 batch(es)
# [Batch 1/2] Planning GH-123, GH-124, GH-125...
# ✓ GH-123: SOL-GH-123-a7x9 (3 tasks)
# ✓ GH-124: SOL-GH-124-b3m2 (4 tasks)
# ✓ GH-125: SOL-GH-125-c8k1 (2 tasks)

Plan with Failure Retry

/issue:plan ISS-20251229-001
# Agent analyzes previous failure from issue.feedback
# Avoids same approach that failed before
# Creates alternative solution with verification steps

Multiple Solutions Selection

/issue:plan GH-999
# Agent generates 2 alternative solutions
# Interactive prompt:
#   Issue GH-999: which solution to bind?
#   [1] SOL-GH-999-a1b2 (4 tasks) - Refactor approach
#   [2] SOL-GH-999-c3d4 (6 tasks) - Rewrite approach

Issue Lifecycle Flow

graph TB
    A[Issues to Plan] --> B[Load Issue Metadata]
    B --> C[Intelligent Grouping]
    C --> D[Launch Agents Parallel]
    D --> E1[Agent Batch 1]
    D --> E2[Agent Batch 2]
    E1{Analyze
Failures?}
    E2{Analyze
Failures?}
    E1 -->|Yes| F1[Extract Failure Patterns]
    E1 -->|No| G1[Explore Codebase]
    E2 -->|Yes| F2[Extract Failure Patterns]
    E2 -->|No| G2[Explore Codebase]
    F1 --> G1
    F2 --> G2
    G1 --> H1[Generate Solution]
    G2 --> H2[Generate Solution]
    H1 --> I{Single
Solution?}
    H2 --> I
    I -->|Yes| J[Auto-Bind]
    I -->|No| K[User Selection]
    K --> L[Bind Selected]
    J --> M[Status: Planned]
    L --> M

Planning Workflow

Phase 1: Issue Loading

# Brief metadata only (to avoid context overflow)
ccw issue list --status pending,registered --json

Returns: Array of {id, title, tags}

Phase 2: Agent Exploration (Parallel)

Each agent performs:

1. Fetch full issue details

   ccw issue status <id> --json
   

2. Analyze failure history (if exists)

   • Extract issue.feedback where type='failure', stage='execute'
   • Parse error_type, message, task_id, solution_id
   • Identify repeated patterns and root causes
   • Design alternative approach

3. Load project context

   • .workflow/project-tech.json (technology stack)
   • .workflow/project-guidelines.json (constraints)

4. Explore codebase (ACE semantic search)

5. Generate solution (following solution-schema.json)

   • Tasks with quantified acceptance criteria
   • Verification steps to prevent same failure
   • Reference to previous failures in approach

6. Write and bind

   • Write to solutions/{issue-id}.jsonl
   • Execute ccw issue bind <issue-id> <solution-id> if single solution

Phase 3: Solution Selection

Multiple solutions → User selects via AskUserQuestion

Phase 4: Summary

## Done: 5 issues → 5 planned

Bound Solutions:
- GH-123: SOL-GH-123-a7x9 (3 tasks)
- GH-124: SOL-GH-124-b3m2 (4 tasks)
- ISS-20251229-001: SOL-ISS-20251229-001-c8k1 (2 tasks)

Next: /issue:queue

Failure-Aware Planning

Feedback Schema

interface FailureFeedback {
  type: 'failure';
  stage: 'execute';
  content: {
    task_id: string;
    solution_id: string;
    error_type: 'test_failure' | 'compilation' | 'timeout' | 'runtime_error';
    message: string;
    timestamp: string;
  };
  created_at: string;
}

Failure Analysis Rules

1. Extract patterns: Repeated errors indicate systemic issues
2. Identify root cause: Test failure vs. compilation vs. timeout
3. Design alternative: Change approach, not just implementation
4. Add prevention: Explicit verification steps for same error
5. Document lessons: Reference failures in solution.approach

CLI Endpoints

Issue Operations

# List pending issues (brief)
ccw issue list --status pending --brief

# Get full issue details (agent use)
ccw issue status <id> --json

# Bind solution to issue
ccw issue bind <issue-id> <solution-id>

# List with bound solutions
ccw issue solutions --status planned --brief

Solution Schema

interface Solution {
  id: string;                    // SOL-{issue-id}-{4-char-uid}
  description: string;
  approach: string;
  tasks: Task[];
  exploration_context: {
    relevant_files: string[];
    dependencies: string[];
    patterns: string[];
  };
  failure_analysis?: {
    previous_failures: string[];
    alternative_approach: string;
    prevention_steps: string[];
  };
  is_bound: boolean;
  created_at: string;
  bound_at?: string;
}

interface Task {
  id: string;                    // T1, T2, T3...
  title: string;
  scope: string;
  action: string;
  implementation: string[];
  acceptance: {
    criteria: string[];
    verification: string[];
  };
  test?: {
    unit?: string[];
    integration?: string[];
    commands?: string[];
  };
}

Related Commands

• issue:new - Create issues before planning
• issue:queue - Form execution queue from planned issues
• issue:execute - Execute planned solutions
• issue:from-brainstorm - Convert brainstorm to planned issue
• issue:convert-to-plan - Convert existing plans to issues

Best Practices

1. Plan in batches: Default 3 issues per batch for optimal performance
2. Review failures: Check issue feedback before replanning
3. Verify conflicts: Agent reports file conflicts across issues
4. GitHub issues: Agent adds final task to comment on GitHub issue
5. Acceptance criteria: Ensure tasks have quantified success metrics
6. Test coverage: Each task should include verification steps

Troubleshooting

Error	Cause	Resolution
No pending issues	All issues already planned	Create new issues or use --all-pending flag
Agent timeout	Large codebase exploration	Reduce batch size or limit scope
No solutions generated	Insufficient context	Provide more detailed issue description
Solution conflicts	Multiple issues touch same files	Agent reports conflicts, resolve manually
Bind failure	Solution file write error	Check permissions, retry