mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
feat: initialize monorepo with package.json for CCW workflow platform
This commit is contained in:
catlog22
288
ccw/docs-site/docs/commands/issue/issue-plan.md
Normal file
288
ccw/docs-site/docs/commands/issue/issue-plan.md
Normal file
@@ -0,0 +1,288 @@
|
||||
---
|
||||
title: issue:plan
|
||||
sidebar_label: issue:plan
|
||||
sidebar_position: 3
|
||||
description: 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
/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
|
||||
|
||||
```bash
|
||||
/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
|
||||
|
||||
```bash
|
||||
/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
|
||||
|
||||
```mermaid
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
## 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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```typescript
|
||||
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](./issue-new.md)** - Create issues before planning
|
||||
- **[issue:queue](./issue-queue.md)** - Form execution queue from planned issues
|
||||
- **[issue:execute](./issue-execute.md)** - Execute planned solutions
|
||||
- **[issue:from-brainstorm](./issue-from-brainstorm.md)** - Convert brainstorm to planned issue
|
||||
- **[issue:convert-to-plan](./issue-convert-to-plan.md)** - 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 |
|
||||
Reference in New Issue
Block a user