mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
feat: 更新任务生成和执行限制，优化多模块任务管理
This commit is contained in:
catlog22
@@ -767,13 +767,13 @@ Generate at `.workflow/active/{session_id}/TODO_LIST.md`:
|
||||
Use `analysis_results.complexity` or task count to determine structure:
|
||||
|
||||
**Single Module Mode**:
|
||||
- **Simple Tasks** (≤5 tasks): Flat structure
|
||||
- **Medium Tasks** (6-12 tasks): Flat structure
|
||||
- **Complex Tasks** (>12 tasks): Re-scope required (maximum 12 tasks hard limit)
|
||||
- **Simple Tasks** (≤4 tasks): Flat structure
|
||||
- **Medium Tasks** (5-8 tasks): Flat structure
|
||||
- **Complex Tasks** (>8 tasks): Re-scope required (maximum 8 tasks hard limit)
|
||||
|
||||
**Multi-Module Mode** (N+1 parallel planning):
|
||||
- **Per-module limit**: ≤9 tasks per module
|
||||
- **Total limit**: Sum of all module tasks ≤27 (3 modules × 9 tasks)
|
||||
- **Per-module limit**: ≤6 tasks per module
|
||||
- **Total limit**: No total limit (each module independently capped at 6 tasks)
|
||||
- **Task ID format**: `IMPL-{prefix}{seq}` (e.g., IMPL-A1, IMPL-B1)
|
||||
- **Structure**: Hierarchical by module in IMPL_PLAN.md and TODO_LIST.md
|
||||
|
||||
@@ -848,7 +848,7 @@ Use `analysis_results.complexity` or task count to determine structure:
|
||||
- **Compute CLI execution strategy**: Based on `depends_on`, set `cli_execution.strategy` (new/resume/fork/merge_fork)
|
||||
- Map artifacts: Use artifacts_inventory to populate task.context.artifacts array
|
||||
- Add MCP integration: Include MCP tool steps in flow_control.pre_analysis when capabilities available
|
||||
- Validate task count: Maximum 12 tasks hard limit, request re-scope if exceeded
|
||||
- Validate task count: Maximum 8 tasks (single module) or 6 tasks per module (multi-module), request re-scope if exceeded
|
||||
- Use session paths: Construct all paths using provided session_id
|
||||
- Link documents properly: Use correct linking format (📋 for JSON, ✅ for summaries)
|
||||
- Run validation checklist: Verify all quantification requirements before finalizing task JSONs
|
||||
@@ -862,7 +862,7 @@ Use `analysis_results.complexity` or task count to determine structure:
|
||||
- Load files directly (use provided context package instead)
|
||||
- Assume default locations (always use session_id in paths)
|
||||
- Create circular dependencies in task.depends_on
|
||||
- Exceed 12 tasks without re-scoping
|
||||
- Exceed 8 tasks (single module) or 6 tasks per module (multi-module) without re-scoping
|
||||
- Skip artifact integration when artifacts_inventory is provided
|
||||
- Ignore MCP capabilities when available
|
||||
- Use fixed pre-analysis steps without task-specific adaptation
|
||||
|
||||
832
.claude/commands/ccw-debug.md
Normal file
832
.claude/commands/ccw-debug.md
Normal file
@@ -0,0 +1,832 @@
|
||||
---
|
||||
name: ccw-debug
|
||||
description: Aggregated debug command - combines debugging diagnostics and test verification in a synergistic workflow supporting cli-quick / debug-first / test-first / bidirectional-verification modes
|
||||
argument-hint: "[--mode cli|debug|test|bidirectional] [--yes|-y] [--hotfix] \"bug description or error message\""
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), AskUserQuestion(*), Read(*), Bash(*)
|
||||
---
|
||||
|
||||
# CCW-Debug Aggregated Command
|
||||
|
||||
## Core Concept
|
||||
|
||||
**Aggregated Debug Command** - Combines debugging diagnostics and test verification in a synergistic workflow. Not a simple concatenation of two commands, but intelligent orchestration based on mode selection.
|
||||
|
||||
### Four Execution Modes
|
||||
|
||||
| Mode | Workflow | Use Case | Characteristics |
|
||||
|------|----------|----------|-----------------|
|
||||
| **CLI Quick** (cli) | Direct CLI Analysis → Fix Suggestions | Simple issues, quick diagnosis | Fastest, minimal workflow, recommendation-only |
|
||||
| **Debug First** (debug) | Debug → Analyze Hypotheses → Apply Fix → Test Verification | Root cause unclear, requires exploration | Starts with exploration, Gemini-assisted |
|
||||
| **Test First** (test) | Generate Tests → Execute → Analyze Failures → CLI Fixes | Code implemented, needs test validation | Driven by test coverage, auto-iterates |
|
||||
| **Bidirectional Verification** (bidirectional) | Parallel: Debug + Test → Merge Findings → Unified Fix | Complex systems, ambiguous symptoms | Parallel execution, converged insights |
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# CLI quick mode: fastest, recommendation-only (new!)
|
||||
/ccw-debug --mode cli "Login failed: token validation error"
|
||||
|
||||
# Default mode: debug-first (recommended for most scenarios)
|
||||
/ccw-debug "Login failed: token validation error"
|
||||
|
||||
# Test-first mode
|
||||
/ccw-debug --mode test "User permission check failure"
|
||||
|
||||
# Bidirectional verification mode (complex issues)
|
||||
/ccw-debug --mode bidirectional "Payment flow multiple failures"
|
||||
|
||||
# Auto mode (skip all confirmations)
|
||||
/ccw-debug --yes "Quick fix: database connection timeout"
|
||||
|
||||
# Production hotfix (minimal diagnostics)
|
||||
/ccw-debug --hotfix --yes "Production: API returns 500"
|
||||
```
|
||||
|
||||
### Mode Selection Guide
|
||||
|
||||
**Choose "CLI Quick"** when:
|
||||
- Need immediate diagnosis, not execution
|
||||
- Want quick recommendations without workflows
|
||||
- Simple issues with clear symptoms
|
||||
- Just need fix suggestions, no auto-application
|
||||
- Time is critical, prefer fast output
|
||||
- Want to review CLI analysis before action
|
||||
|
||||
**Choose "Debug First"** when:
|
||||
- Root cause is unclear
|
||||
- Error messages are incomplete or vague
|
||||
- Need to understand code execution flow
|
||||
- Issues involve multi-module interactions
|
||||
|
||||
**Choose "Test First"** when:
|
||||
- Code is fully implemented
|
||||
- Need test coverage verification
|
||||
- Have clear failure cases
|
||||
- Want automated iterative fixes
|
||||
|
||||
**Choose "Bidirectional Verification"** when:
|
||||
- System is complex (multiple subsystems)
|
||||
- Problem symptoms are ambiguous (multiple possible root causes)
|
||||
- Need multi-angle validation
|
||||
- Time allows parallel analysis
|
||||
|
||||
---
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Overall Process
|
||||
|
||||
```
|
||||
Phase 1: Intent Analysis & Mode Selection
|
||||
├─ Parse --mode flag or recommend mode
|
||||
├─ Check --hotfix and --yes flags
|
||||
└─ Determine workflow path
|
||||
|
||||
Phase 2: Initialization
|
||||
├─ CLI Quick: Lightweight init (no session directory needed)
|
||||
├─ Others: Create unified session directory (.workflow/.ccw-debug/)
|
||||
├─ Setup TodoWrite tracking
|
||||
└─ Prepare session context
|
||||
|
||||
Phase 3: Execute Corresponding Workflow
|
||||
├─ CLI Quick: ccw cli → Diagnosis Report → Optional: Escalate to debug/test/apply fix
|
||||
├─ Debug First: /workflow:debug-with-file → Fix → /workflow:test-fix-gen → /workflow:test-cycle-execute
|
||||
├─ Test First: /workflow:test-fix-gen → /workflow:test-cycle-execute → CLI analyze failures
|
||||
└─ Bidirectional: [/workflow:debug-with-file] ∥ [/workflow:test-fix-gen → test-cycle-execute]
|
||||
|
||||
Phase 4: Merge Findings (Bidirectional Mode) / Escalation Decision (CLI Mode)
|
||||
├─ CLI Quick: Present results → Ask user: Apply fix? Escalate? Done?
|
||||
├─ Bidirectional: Converge findings from both workflows
|
||||
├─ Identify consistent and conflicting root cause analyses
|
||||
└─ Generate unified fix plan
|
||||
|
||||
Phase 5: Completion & Follow-up
|
||||
├─ Generate summary report
|
||||
├─ Provide next step recommendations
|
||||
└─ Optional: Expand to issues (testing/enhancement/refactoring/documentation)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow Details
|
||||
|
||||
### Mode 0: CLI Quick (Minimal Debug Method)
|
||||
|
||||
**Best For**: Fast recommendations without full workflow overhead
|
||||
|
||||
**Workflow**:
|
||||
```
|
||||
User Input → Quick Context Gather → ccw cli (Gemini/Qwen/Codex)
|
||||
↓
|
||||
Analysis Report
|
||||
↓
|
||||
Fix Recommendations
|
||||
↓
|
||||
Optional: User Decision
|
||||
┌──────────────┼──────────────┐
|
||||
↓ ↓ ↓
|
||||
Apply Fix Escalate Mode Done
|
||||
(debug/test)
|
||||
```
|
||||
|
||||
**Execution Steps**:
|
||||
|
||||
1. **Lightweight Context Gather** (Phase 2)
|
||||
```javascript
|
||||
// No session directory needed for CLI mode
|
||||
const tempContext = {
|
||||
bug_description: bug_description,
|
||||
timestamp: getUtc8ISOString(),
|
||||
mode: "cli"
|
||||
}
|
||||
|
||||
// Quick context discovery (30s max)
|
||||
// - Read error file if path provided
|
||||
// - Extract error patterns from description
|
||||
// - Identify likely affected files (basic grep)
|
||||
```
|
||||
|
||||
2. **Execute CLI Analysis** (Phase 3)
|
||||
```bash
|
||||
# Use ccw cli with bug diagnosis template
|
||||
ccw cli -p "
|
||||
PURPOSE: Quick bug diagnosis for immediate recommendations
|
||||
|
||||
TASK:
|
||||
• Analyze bug symptoms: ${bug_description}
|
||||
• Identify likely root cause
|
||||
• Provide actionable fix recommendations (code snippets if possible)
|
||||
• Assess fix confidence level
|
||||
|
||||
MODE: analysis
|
||||
|
||||
CONTEXT: ${contextFiles.length > 0 ? '@' + contextFiles.join(' @') : 'Bug description only'}
|
||||
|
||||
EXPECTED:
|
||||
- Root cause hypothesis (1-2 sentences)
|
||||
- Fix strategy (immediate/comprehensive/refactor)
|
||||
- Code snippets or file modification suggestions
|
||||
- Confidence level: High/Medium/Low
|
||||
- Risk assessment
|
||||
|
||||
CONSTRAINTS: Quick analysis, 2-5 minutes max
|
||||
" --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause
|
||||
```
|
||||
|
||||
3. **Present Results** (Phase 4)
|
||||
```
|
||||
## CLI Quick Analysis Complete
|
||||
|
||||
**Issue**: [bug_description]
|
||||
**Analysis Time**: [duration]
|
||||
**Confidence**: [High/Medium/Low]
|
||||
|
||||
### Root Cause
|
||||
[1-2 sentence hypothesis]
|
||||
|
||||
### Fix Strategy
|
||||
[immediate_patch | comprehensive_fix | refactor]
|
||||
|
||||
### Recommended Changes
|
||||
|
||||
**File**: src/module/file.ts
|
||||
```typescript
|
||||
// Change line 45-50
|
||||
- old code
|
||||
+ new code
|
||||
```
|
||||
|
||||
**Rationale**: [why this fix]
|
||||
**Risk**: [Low/Medium/High] - [risk description]
|
||||
|
||||
### Confidence Assessment
|
||||
- Analysis confidence: [percentage]
|
||||
- Recommendation: [apply immediately | review first | escalate to full debug]
|
||||
```
|
||||
|
||||
4. **User Decision** (Phase 5)
|
||||
```javascript
|
||||
// Parse --yes flag
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
if (autoYes && confidence === 'High') {
|
||||
// Auto-apply fix
|
||||
console.log('[--yes + High confidence] Auto-applying fix...')
|
||||
applyFixFromCLIRecommendation(cliOutput)
|
||||
} else {
|
||||
// Ask user
|
||||
const decision = AskUserQuestion({
|
||||
questions: [{
|
||||
question: `CLI analysis complete (${confidence} confidence). What next?`,
|
||||
header: "Decision",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Apply Fix", description: "Apply recommended changes immediately" },
|
||||
{ label: "Escalate to Debug", description: "Switch to debug-first for deeper analysis" },
|
||||
{ label: "Escalate to Test", description: "Switch to test-first for validation" },
|
||||
{ label: "Review Only", description: "Just review, no action" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
|
||||
if (decision === "Apply Fix") {
|
||||
applyFixFromCLIRecommendation(cliOutput)
|
||||
} else if (decision === "Escalate to Debug") {
|
||||
// Re-invoke ccw-debug with --mode debug
|
||||
SlashCommand(command=`/ccw-debug --mode debug "${bug_description}"`)
|
||||
} else if (decision === "Escalate to Test") {
|
||||
// Re-invoke ccw-debug with --mode test
|
||||
SlashCommand(command=`/ccw-debug --mode test "${bug_description}"`)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Characteristics**:
|
||||
- **Speed**: 2-5 minutes total (fastest mode)
|
||||
- **Session**: No persistent session directory (lightweight)
|
||||
- **Output**: Recommendation report only
|
||||
- **Execution**: Optional, user-controlled
|
||||
- **Escalation**: Can upgrade to full debug/test workflows
|
||||
|
||||
**Limitations**:
|
||||
- No hypothesis iteration (single-shot analysis)
|
||||
- No automatic test generation
|
||||
- No instrumentation/logging
|
||||
- Best for clear symptoms with localized fixes
|
||||
|
||||
---
|
||||
|
||||
### Mode 1: Debug First
|
||||
|
||||
**Best For**: Issues requiring root cause exploration
|
||||
|
||||
**Workflow**:
|
||||
```
|
||||
User Input → Session Init → /workflow:debug-with-file
|
||||
↓
|
||||
Generate understanding.md + hypotheses
|
||||
↓
|
||||
User reproduces issue, analyze logs
|
||||
↓
|
||||
Gemini validates hypotheses
|
||||
↓
|
||||
Apply fix code
|
||||
↓
|
||||
/workflow:test-fix-gen
|
||||
↓
|
||||
/workflow:test-cycle-execute
|
||||
↓
|
||||
Generate unified report
|
||||
```
|
||||
|
||||
**Execution Steps**:
|
||||
|
||||
1. **Session Initialization** (Phase 2)
|
||||
```javascript
|
||||
const sessionId = `CCWD-${bugSlug}-${dateStr}`
|
||||
const sessionFolder = `.workflow/.ccw-debug/${sessionId}`
|
||||
bash(`mkdir -p ${sessionFolder}`)
|
||||
|
||||
// Record mode selection
|
||||
const modeConfig = {
|
||||
mode: "debug",
|
||||
original_input: bug_description,
|
||||
timestamp: getUtc8ISOString(),
|
||||
flags: { hotfix, autoYes }
|
||||
}
|
||||
Write(`${sessionFolder}/mode-config.json`, JSON.stringify(modeConfig, null, 2))
|
||||
```
|
||||
|
||||
2. **Start Debug** (Phase 3)
|
||||
```javascript
|
||||
SlashCommand(command=`/workflow:debug-with-file "${bug_description}"`)
|
||||
|
||||
// Update TodoWrite
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "Phase 1: Debug & Analysis", status: "completed" },
|
||||
{ content: "Phase 2: Apply Fix from Debug Findings", status: "in_progress" },
|
||||
{ content: "Phase 3: Generate & Execute Tests", status: "pending" },
|
||||
{ content: "Phase 4: Generate Report", status: "pending" }
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
3. **Apply Fix** (Handled by debug command)
|
||||
|
||||
4. **Test Generation & Execution**
|
||||
```javascript
|
||||
// Auto-continue after debug command completes
|
||||
SlashCommand(command=`/workflow:test-fix-gen "Test validation for: ${bug_description}"`)
|
||||
SlashCommand(command="/workflow:test-cycle-execute")
|
||||
```
|
||||
|
||||
5. **Generate Report** (Phase 5)
|
||||
```
|
||||
## Debug-First Workflow Completed
|
||||
|
||||
**Issue**: [bug_description]
|
||||
**Mode**: Debug First
|
||||
**Session**: [sessionId]
|
||||
|
||||
### Debug Phase Results
|
||||
- Root Cause: [extracted from understanding.md]
|
||||
- Hypothesis Confirmation: [from hypotheses.json]
|
||||
- Fixes Applied: [list of modified files]
|
||||
|
||||
### Test Phase Results
|
||||
- Tests Created: [test files generated by IMPL-001]
|
||||
- Pass Rate: [final test pass rate]
|
||||
- Iteration Count: [fix iterations]
|
||||
|
||||
### Key Findings
|
||||
- [learning points from debugging]
|
||||
- [coverage insights from testing]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Mode 2: Test First
|
||||
|
||||
**Best For**: Implemented code needing test validation
|
||||
|
||||
**Workflow**:
|
||||
```
|
||||
User Input → Session Init → /workflow:test-fix-gen
|
||||
↓
|
||||
Generate test tasks (IMPL-001, IMPL-002)
|
||||
↓
|
||||
/workflow:test-cycle-execute
|
||||
↓
|
||||
Auto-iterate: Test → Analyze Failures → CLI Fix
|
||||
↓
|
||||
Until pass rate ≥ 95%
|
||||
↓
|
||||
Generate report
|
||||
```
|
||||
|
||||
**Execution Steps**:
|
||||
|
||||
1. **Session Initialization** (Phase 2)
|
||||
```javascript
|
||||
const modeConfig = {
|
||||
mode: "test",
|
||||
original_input: bug_description,
|
||||
timestamp: getUtc8ISOString(),
|
||||
flags: { hotfix, autoYes }
|
||||
}
|
||||
```
|
||||
|
||||
2. **Generate Tests** (Phase 3)
|
||||
```javascript
|
||||
SlashCommand(command=`/workflow:test-fix-gen "${bug_description}"`)
|
||||
|
||||
// Update TodoWrite
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "Phase 1: Generate Tests", status: "completed" },
|
||||
{ content: "Phase 2: Execute & Fix Tests", status: "in_progress" },
|
||||
{ content: "Phase 3: Final Validation", status: "pending" },
|
||||
{ content: "Phase 4: Generate Report", status: "pending" }
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
3. **Execute & Iterate** (Phase 3 cont.)
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:test-cycle-execute")
|
||||
|
||||
// test-cycle-execute handles:
|
||||
// - Execute tests
|
||||
// - Analyze failures
|
||||
// - Generate fix tasks via CLI
|
||||
// - Iterate fixes until pass
|
||||
```
|
||||
|
||||
4. **Generate Report** (Phase 5)
|
||||
|
||||
---
|
||||
|
||||
### Mode 3: Bidirectional Verification
|
||||
|
||||
**Best For**: Complex systems, multi-dimensional analysis
|
||||
|
||||
**Workflow**:
|
||||
```
|
||||
User Input → Session Init → Parallel execution:
|
||||
┌──────────────────────────────┐
|
||||
│ │
|
||||
↓ ↓
|
||||
/workflow:debug-with-file /workflow:test-fix-gen
|
||||
│ │
|
||||
Generate hypotheses & understanding Generate test tasks
|
||||
│ │
|
||||
↓ ↓
|
||||
Apply debug fixes /workflow:test-cycle-execute
|
||||
│ │
|
||||
└──────────────┬───────────────┘
|
||||
↓
|
||||
Phase 4: Merge Findings
|
||||
├─ Converge root cause analyses
|
||||
├─ Identify consistency (mutual validation)
|
||||
├─ Identify conflicts (need coordination)
|
||||
└─ Generate unified report
|
||||
```
|
||||
|
||||
**Execution Steps**:
|
||||
|
||||
1. **Parallel Execution** (Phase 3)
|
||||
```javascript
|
||||
// Start debug
|
||||
const debugTask = SlashCommand(
|
||||
command=`/workflow:debug-with-file "${bug_description}"`,
|
||||
run_in_background=false
|
||||
)
|
||||
|
||||
// Start test generation (synchronous execution, SlashCommand blocks)
|
||||
const testTask = SlashCommand(
|
||||
command=`/workflow:test-fix-gen "${bug_description}"`,
|
||||
run_in_background=false
|
||||
)
|
||||
|
||||
// Execute test cycle
|
||||
const testCycleTask = SlashCommand(
|
||||
command="/workflow:test-cycle-execute",
|
||||
run_in_background=false
|
||||
)
|
||||
```
|
||||
|
||||
2. **Merge Findings** (Phase 4)
|
||||
```javascript
|
||||
// Read debug results
|
||||
const understandingMd = Read(`${debugSessionFolder}/understanding.md`)
|
||||
const hypothesesJson = JSON.parse(Read(`${debugSessionFolder}/hypotheses.json`))
|
||||
|
||||
// Read test results
|
||||
const testResultsJson = JSON.parse(Read(`${testSessionFolder}/.process/test-results.json`))
|
||||
const fixPlanJson = JSON.parse(Read(`${testSessionFolder}/.task/IMPL-002.json`))
|
||||
|
||||
// Merge analysis
|
||||
const convergence = {
|
||||
debug_root_cause: hypothesesJson.confirmed_hypothesis,
|
||||
test_failure_pattern: testResultsJson.failures,
|
||||
consistency: analyzeConsistency(debugRootCause, testFailures),
|
||||
conflicts: identifyConflicts(debugRootCause, testFailures),
|
||||
unified_root_cause: mergeRootCauses(debugRootCause, testFailures),
|
||||
recommended_fix: selectBestFix(debugRootCause, testRootCause)
|
||||
}
|
||||
```
|
||||
|
||||
3. **Generate Report** (Phase 5)
|
||||
```
|
||||
## Bidirectional Verification Workflow Completed
|
||||
|
||||
**Issue**: [bug_description]
|
||||
**Mode**: Bidirectional Verification
|
||||
|
||||
### Debug Findings
|
||||
- Root Cause (hypothesis): [from understanding.md]
|
||||
- Confidence: [from hypotheses.json]
|
||||
- Key code paths: [file:line]
|
||||
|
||||
### Test Findings
|
||||
- Failure pattern: [list of failing tests]
|
||||
- Error type: [error type]
|
||||
- Impact scope: [affected modules]
|
||||
|
||||
### Merged Analysis
|
||||
- ✓ Consistent: Both workflows identified same root cause
|
||||
- ⚠ Conflicts: [list any conflicts]
|
||||
- → Unified Root Cause: [final confirmed root cause]
|
||||
|
||||
### Recommended Fix
|
||||
- Strategy: [selected fix strategy]
|
||||
- Rationale: [why this strategy]
|
||||
- Risks: [known risks]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Command Line Interface
|
||||
|
||||
### Complete Syntax
|
||||
|
||||
```bash
|
||||
/ccw-debug [OPTIONS] <BUG_DESCRIPTION>
|
||||
|
||||
Options:
|
||||
--mode <cli|debug|test|bidirectional> Execution mode (default: debug)
|
||||
--yes, -y Auto mode (skip all confirmations)
|
||||
--hotfix, -h Production hotfix mode (only for debug mode)
|
||||
--no-tests Skip test generation in debug-first mode
|
||||
--skip-report Don't generate final report
|
||||
--resume <session-id> Resume interrupted session
|
||||
|
||||
Arguments:
|
||||
<BUG_DESCRIPTION> Issue description, error message, or .md file path
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# CLI quick mode: fastest, recommendation-only (NEW!)
|
||||
/ccw-debug --mode cli "User login timeout"
|
||||
/ccw-debug --mode cli --yes "Quick fix: API 500 error" # Auto-apply if high confidence
|
||||
|
||||
# Debug first (default)
|
||||
/ccw-debug "User login timeout"
|
||||
|
||||
# Test first
|
||||
/ccw-debug --mode test "Payment validation failure"
|
||||
|
||||
# Bidirectional verification
|
||||
/ccw-debug --mode bidirectional "Multi-module data consistency issue"
|
||||
|
||||
# Hotfix auto mode
|
||||
/ccw-debug --hotfix --yes "API 500 error"
|
||||
|
||||
# Debug first, skip tests
|
||||
/ccw-debug --no-tests "Understand code flow"
|
||||
|
||||
# Resume interrupted session
|
||||
/ccw-debug --resume CCWD-login-timeout-2025-01-27
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Structure
|
||||
|
||||
### File Organization
|
||||
|
||||
```
|
||||
.workflow/.ccw-debug/CCWD-{slug}-{date}/
|
||||
├── mode-config.json # Mode configuration and flags
|
||||
├── session-manifest.json # Session index and status
|
||||
├── final-report.md # Final report
|
||||
│
|
||||
├── debug/ # Debug workflow (if mode includes debug)
|
||||
│ ├── debug-session-id.txt
|
||||
│ ├── understanding.md
|
||||
│ ├── hypotheses.json
|
||||
│ └── debug.log
|
||||
│
|
||||
├── test/ # Test workflow (if mode includes test)
|
||||
│ ├── test-session-id.txt
|
||||
│ ├── IMPL_PLAN.md
|
||||
│ ├── test-results.json
|
||||
│ └── iteration-state.json
|
||||
│
|
||||
└── fusion/ # Fusion analysis (bidirectional mode)
|
||||
├── convergence-analysis.json
|
||||
├── consistency-report.md
|
||||
└── unified-root-cause.json
|
||||
```
|
||||
|
||||
### Session State Management
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "CCWD-login-timeout-2025-01-27",
|
||||
"mode": "debug|test|bidirectional",
|
||||
"status": "running|completed|failed|paused",
|
||||
"phases": {
|
||||
"phase_1": { "status": "completed", "timestamp": "..." },
|
||||
"phase_2": { "status": "in_progress", "timestamp": "..." },
|
||||
"phase_3": { "status": "pending" },
|
||||
"phase_4": { "status": "pending" },
|
||||
"phase_5": { "status": "pending" }
|
||||
},
|
||||
"sub_sessions": {
|
||||
"debug_session": "DBG-...",
|
||||
"test_session": "WFS-test-..."
|
||||
},
|
||||
"artifacts": {
|
||||
"debug_understanding": "...",
|
||||
"test_results": "...",
|
||||
"fusion_analysis": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode Selection Logic
|
||||
|
||||
### Auto Mode Recommendation
|
||||
|
||||
When user doesn't specify `--mode`, recommend based on input analysis:
|
||||
|
||||
```javascript
|
||||
function recommendMode(bugDescription) {
|
||||
const indicators = {
|
||||
cli_signals: [
|
||||
/quick|fast|simple|immediate/,
|
||||
/recommendation|suggest|advice/,
|
||||
/just need|only want|quick look/,
|
||||
/straightforward|obvious|clear/
|
||||
],
|
||||
debug_signals: [
|
||||
/unclear|don't know|maybe|uncertain|why/,
|
||||
/error|crash|fail|exception|stack trace/,
|
||||
/execution flow|code path|how does/
|
||||
],
|
||||
test_signals: [
|
||||
/test|coverage|verify|pass|fail/,
|
||||
/implementation|implemented|complete/,
|
||||
/case|scenario|should/
|
||||
],
|
||||
complex_signals: [
|
||||
/multiple|all|system|integration/,
|
||||
/module|subsystem|network|distributed/,
|
||||
/concurrent|async|race/
|
||||
]
|
||||
}
|
||||
|
||||
let score = { cli: 0, debug: 0, test: 0, bidirectional: 0 }
|
||||
|
||||
// CLI signals (lightweight preference)
|
||||
for (const pattern of indicators.cli_signals) {
|
||||
if (pattern.test(bugDescription)) score.cli += 3
|
||||
}
|
||||
|
||||
// Debug signals
|
||||
for (const pattern of indicators.debug_signals) {
|
||||
if (pattern.test(bugDescription)) score.debug += 2
|
||||
}
|
||||
|
||||
// Test signals
|
||||
for (const pattern of indicators.test_signals) {
|
||||
if (pattern.test(bugDescription)) score.test += 2
|
||||
}
|
||||
|
||||
// Complex signals (prefer bidirectional for complex issues)
|
||||
for (const pattern of indicators.complex_signals) {
|
||||
if (pattern.test(bugDescription)) {
|
||||
score.bidirectional += 3
|
||||
score.cli -= 2 // Complex issues not suitable for CLI quick
|
||||
}
|
||||
}
|
||||
|
||||
// If description is short and has clear error, prefer CLI
|
||||
if (bugDescription.length < 100 && /error|fail|crash/.test(bugDescription)) {
|
||||
score.cli += 2
|
||||
}
|
||||
|
||||
// Return highest scoring mode
|
||||
return Object.entries(score).sort((a, b) => b[1] - a[1])[0][0]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When to Use Each Mode
|
||||
|
||||
| Issue Characteristic | Recommended Mode | Rationale |
|
||||
|----------------------|-----------------|-----------|
|
||||
| Simple error, clear symptoms | CLI Quick | Fastest recommendation |
|
||||
| Incomplete error info, requires exploration | Debug First | Deep diagnostic capability |
|
||||
| Code complete, needs test coverage | Test First | Automated iterative fixes |
|
||||
| Cross-module issue, ambiguous symptoms | Bidirectional | Multi-angle insights |
|
||||
| Production failure, needs immediate guidance | CLI Quick + --yes | Fastest guidance, optional escalation |
|
||||
| Production failure, needs safe fix | Debug First + --hotfix | Minimal diagnosis time |
|
||||
| Want to understand why it failed | Debug First | Records understanding evolution |
|
||||
| Want to ensure all scenarios pass | Test First | Complete coverage-driven |
|
||||
|
||||
### Performance Tips
|
||||
|
||||
- **CLI Quick**: 2-5 minutes, no file I/O, recommendation-only
|
||||
- **Debug First**: Usually requires manual issue reproduction (after logging added), then 15-30 min
|
||||
- **Test First**: Fully automated, 20-45 min depending on test suite size
|
||||
- **Bidirectional**: Most comprehensive but slowest (parallel workflows), 30-60 min
|
||||
|
||||
### Workflow Continuity
|
||||
|
||||
- **CLI Quick**: Can escalate to debug/test/apply fix based on user decision
|
||||
- **Debug First**: Auto-launches test generation and execution after completion
|
||||
- **Test First**: With high failure rates suggests switching to debug mode for root cause
|
||||
- **Bidirectional**: Always executes complete flow
|
||||
|
||||
---
|
||||
|
||||
## Follow-up Expansion
|
||||
|
||||
After completion, offer to expand to issues:
|
||||
|
||||
```
|
||||
## Done! What's next?
|
||||
|
||||
- [ ] Create Test issue (improve test coverage)
|
||||
- [ ] Create Enhancement issue (optimize code quality)
|
||||
- [ ] Create Refactor issue (improve architecture)
|
||||
- [ ] Create Documentation issue (record learnings)
|
||||
- [ ] Don't create any issue, end workflow
|
||||
```
|
||||
|
||||
Selected items call: `/issue:new "{issue summary} - {dimension}"`
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | CLI Quick | Debug First | Test First | Bidirectional |
|
||||
|-------|-----------|-------------|-----------|---------------|
|
||||
| Session creation failed | N/A (no session) | Retry → abort | Retry → abort | Retry → abort |
|
||||
| CLI analysis failed | Retry with fallback tool → manual | N/A | N/A | N/A |
|
||||
| Diagnosis/test failed | N/A | Continue with partial results | Direct failure | Use alternate workflow results |
|
||||
| Low confidence result | Ask escalate or review | N/A | N/A | N/A |
|
||||
| Merge conflicts | N/A | N/A | N/A | Select highest confidence plan |
|
||||
| Fix application failed | Report error, no auto-retry | Request manual fix | Mark failed, request intervention | Try alternative plan |
|
||||
|
||||
---
|
||||
|
||||
## Relationship with ccw Command
|
||||
|
||||
| Feature | ccw | ccw-debug |
|
||||
|---------|-----|----------|
|
||||
| **Design** | General workflow orchestration | Debug + test aggregation |
|
||||
| **Intent Detection** | ✅ Detects task type | ✅ Detects issue type |
|
||||
| **Automation** | ✅ Auto-selects workflow | ✅ Auto-selects mode |
|
||||
| **Quick Mode** | ❌ None | ✅ CLI Quick (2-5 min) |
|
||||
| **Parallel Execution** | ❌ Sequential | ✅ Bidirectional mode parallel |
|
||||
| **Fusion Analysis** | ❌ None | ✅ Bidirectional mode fusion |
|
||||
| **Workflow Scope** | Broad (feature/bugfix/tdd/ui etc.) | Deep focus (debug + test) |
|
||||
| **CLI Integration** | Yes | Yes (4 levels: quick/deep/iterative/fusion) |
|
||||
|
||||
---
|
||||
|
||||
## Usage Recommendations
|
||||
|
||||
1. **First Time**: Use default mode (debug-first), observe workflow
|
||||
2. **Quick Decision**: Use CLI Quick (--mode cli) for immediate recommendations
|
||||
3. **Quick Fix**: Use `--hotfix --yes` for minimal diagnostics (debug mode)
|
||||
4. **Learning**: Use debug-first, read `understanding.md`
|
||||
5. **Complete Validation**: Use bidirectional for multi-dimensional insights
|
||||
6. **Auto Repair**: Use test-first for automatic iteration
|
||||
7. **Escalation**: Start with CLI Quick, escalate to other modes as needed
|
||||
|
||||
---
|
||||
|
||||
## Reference
|
||||
|
||||
### Related Commands
|
||||
|
||||
- `ccw cli` - Direct CLI analysis (used by CLI Quick mode)
|
||||
- `/workflow:debug-with-file` - Deep debug diagnostics
|
||||
- `/workflow:test-fix-gen` - Test generation
|
||||
- `/workflow:test-cycle-execute` - Test execution
|
||||
- `/workflow:lite-fix` - Lightweight fix
|
||||
- `/ccw` - General workflow orchestration
|
||||
|
||||
### Configuration Files
|
||||
|
||||
- `~/.claude/cli-tools.json` - CLI tool configuration (Gemini/Qwen/Codex)
|
||||
- `.workflow/project-tech.json` - Project technology stack
|
||||
- `.workflow/project-guidelines.json` - Project conventions
|
||||
|
||||
### CLI Tool Fallback Chain (for CLI Quick mode)
|
||||
|
||||
When CLI analysis fails, fallback order:
|
||||
1. **Gemini** (primary): `gemini-2.5-pro`
|
||||
2. **Qwen** (fallback): `coder-model`
|
||||
3. **Codex** (fallback): `gpt-5.2`
|
||||
|
||||
---
|
||||
|
||||
## Summary: Mode Selection Decision Tree
|
||||
|
||||
```
|
||||
User calls: /ccw-debug <bug_description>
|
||||
|
||||
┌─ Explicit --mode specified?
|
||||
│ ├─ YES → Use specified mode
|
||||
│ │ ├─ cli → 2-5 min analysis, optionally escalate
|
||||
│ │ ├─ debug → Full debug-with-file workflow
|
||||
│ │ ├─ test → Test-first workflow
|
||||
│ │ └─ bidirectional → Parallel debug + test
|
||||
│ │
|
||||
│ └─ NO → Auto-recommend based on bug description
|
||||
│ ├─ Keywords: "quick", "fast", "simple" → CLI Quick
|
||||
│ ├─ Keywords: "error", "crash", "exception" → Debug First (or CLI if simple)
|
||||
│ ├─ Keywords: "test", "verify", "coverage" → Test First
|
||||
│ └─ Keywords: "multiple", "system", "distributed" → Bidirectional
|
||||
│
|
||||
├─ Check --yes flag
|
||||
│ ├─ YES → Auto-confirm all decisions
|
||||
│ │ ├─ CLI mode: Auto-apply if confidence High
|
||||
│ │ └─ Others: Auto-select default options
|
||||
│ │
|
||||
│ └─ NO → Interactive mode, ask user for confirmations
|
||||
│
|
||||
├─ Check --hotfix flag (debug mode only)
|
||||
│ ├─ YES → Minimal diagnostics, fast fix
|
||||
│ └─ NO → Full analysis
|
||||
│
|
||||
└─ Execute selected mode workflow
|
||||
└─ Return results or escalation options
|
||||
```
|
||||
@@ -69,6 +69,7 @@ function detectTaskType(text) {
|
||||
'bugfix-hotfix': /urgent|production|critical/ && /fix|bug/,
|
||||
'bugfix': /fix|bug|error|crash|fail|debug/,
|
||||
'issue-batch': /issues?|batch/ && /fix|resolve/,
|
||||
'issue-transition': /issue workflow|structured workflow|queue|multi-stage/,
|
||||
'exploration': /uncertain|explore|research|what if/,
|
||||
'multi-perspective': /multi-perspective|compare|cross-verify/,
|
||||
'quick-task': /quick|simple|small/ && /feature|function/,
|
||||
@@ -113,6 +114,7 @@ function selectWorkflow(analysis) {
|
||||
'bugfix-hotfix': { level: 2, flow: 'bugfix.hotfix' },
|
||||
'bugfix': { level: 2, flow: 'bugfix.standard' },
|
||||
'issue-batch': { level: 'Issue', flow: 'issue' },
|
||||
'issue-transition': { level: 2.5, flow: 'rapid-to-issue' }, // Bridge workflow
|
||||
'exploration': { level: 4, flow: 'full' },
|
||||
'quick-task': { level: 1, flow: 'lite-lite-lite' },
|
||||
'ui-design': { level: analysis.complexity === 'high' ? 4 : 3, flow: 'ui' },
|
||||
@@ -147,6 +149,16 @@ function buildCommandChain(workflow, analysis) {
|
||||
])
|
||||
],
|
||||
|
||||
// Level 2 Bridge - Lightweight to Issue Workflow
|
||||
'rapid-to-issue': [
|
||||
// Unit: Quick Implementation【lite-plan → convert-to-plan】
|
||||
{ cmd: '/workflow:lite-plan', args: `"${analysis.goal}"`, unit: 'quick-impl-to-issue' },
|
||||
{ cmd: '/issue:convert-to-plan', args: '--latest-lite-plan -y', unit: 'quick-impl-to-issue' },
|
||||
// Auto-continue to issue workflow
|
||||
{ cmd: '/issue:queue', args: '' },
|
||||
{ cmd: '/issue:execute', args: '--queue auto' }
|
||||
],
|
||||
|
||||
'bugfix.standard': [
|
||||
// Unit: Bug Fix【lite-fix → lite-execute】
|
||||
{ cmd: '/workflow:lite-fix', args: `"${analysis.goal}"`, unit: 'bug-fix' },
|
||||
@@ -409,6 +421,7 @@ Phase 5: Execute Command Chain
|
||||
|-------|------|-------|-----------------------|
|
||||
| "Add API endpoint" | feature (low) | 2 |【lite-plan → lite-execute】→【test-fix-gen → test-cycle-execute】|
|
||||
| "Fix login timeout" | bugfix | 2 |【lite-fix → lite-execute】→【test-fix-gen → test-cycle-execute】|
|
||||
| "Use issue workflow" | issue-transition | 2.5 |【lite-plan → convert-to-plan】→ queue → execute |
|
||||
| "OAuth2 system" | feature (high) | 3 |【plan → plan-verify】→ execute →【review-session-cycle → review-fix】→【test-fix-gen → test-cycle-execute】|
|
||||
| "Implement with TDD" | tdd | 3 |【tdd-plan → execute】→ tdd-verify |
|
||||
| "Uncertain: real-time arch" | exploration | 4 | brainstorm:auto-parallel →【plan → plan-verify】→ execute →【test-fix-gen → test-cycle-execute】|
|
||||
|
||||
@@ -398,7 +398,7 @@ This document contains consolidated constraints and user intent to guide module-
|
||||
- Module: ${module.name} (${module.type})
|
||||
- Focus Paths: ${module.paths.join(', ')}
|
||||
- Task ID Prefix: IMPL-${module.prefix}
|
||||
- Task Limit: ≤9 tasks (hard limit for this module)
|
||||
- Task Limit: ≤6 tasks (hard limit for this module)
|
||||
- Other Modules: ${otherModules.join(', ')} (reference only, do NOT generate tasks for them)
|
||||
|
||||
## SESSION PATHS
|
||||
|
||||
Reference in New Issue
Block a user