156 lines
5.3 KiB
Markdown
156 lines
5.3 KiB
Markdown
# Debug Task Management Patterns
|
|
|
|
Track investigation and debugging pipelines via Claude Native Tasks (TaskCreate, TaskUpdate, TaskList).
|
|
|
|
## When to Create Tasks
|
|
|
|
| Debug Scope | Tasks? | Rationale |
|
|
|-------------|--------|-----------|
|
|
| Single bug, one file | No | Systematic debugging handles directly |
|
|
| Multi-component investigation (3+ steps) | Yes | Track assess → collect → analyze → fix → verify |
|
|
| Parallel log/data collection agents | Yes | Coordinate independent evidence gathering |
|
|
| Performance investigation with multiple layers | Yes | Track bottleneck analysis per layer |
|
|
| CI/CD pipeline failure with 3+ possible causes | Yes | Track hypothesis elimination |
|
|
|
|
**3-Task Rule:** Skip task creation when investigation has <3 meaningful steps.
|
|
|
|
## Investigation Pipeline as Tasks
|
|
|
|
```
|
|
TaskCreate: "Assess incident scope" → pending
|
|
TaskCreate: "Collect logs and evidence" → pending, blockedBy: [assess]
|
|
TaskCreate: "Analyze root cause" → pending, blockedBy: [collect]
|
|
TaskCreate: "Implement fix" → pending, blockedBy: [analyze]
|
|
TaskCreate: "Verify fix resolves issue" → pending, blockedBy: [fix]
|
|
```
|
|
|
|
Maps to investigation-methodology.md 5-step process. Auto-unblocks as each step completes.
|
|
|
|
## Task Schemas
|
|
|
|
### Assess Task
|
|
|
|
```
|
|
TaskCreate(
|
|
subject: "Assess {incident} scope and impact",
|
|
activeForm: "Assessing incident scope",
|
|
description: "Gather symptoms, identify affected components, check recent changes. See investigation-methodology.md Step 1",
|
|
metadata: { debugStage: "assess", incident: "{incident}",
|
|
severity: "P1", effort: "5m" }
|
|
)
|
|
```
|
|
|
|
### Collect Task
|
|
|
|
```
|
|
TaskCreate(
|
|
subject: "Collect evidence for {incident}",
|
|
activeForm: "Collecting evidence",
|
|
description: "Server logs, CI/CD logs, database state, metrics. See log-and-ci-analysis.md",
|
|
metadata: { debugStage: "collect", incident: "{incident}",
|
|
sources: "logs,ci,db", priority: "P1", effort: "10m" },
|
|
addBlockedBy: ["{assess-task-id}"]
|
|
)
|
|
```
|
|
|
|
### Analyze Task
|
|
|
|
```
|
|
TaskCreate(
|
|
subject: "Analyze root cause of {incident}",
|
|
activeForm: "Analyzing root cause",
|
|
description: "Correlate evidence, trace execution paths, identify root cause. See systematic-debugging.md Phase 1-3",
|
|
metadata: { debugStage: "analyze", incident: "{incident}",
|
|
technique: "systematic", priority: "P1", effort: "15m" },
|
|
addBlockedBy: ["{collect-task-id}"]
|
|
)
|
|
```
|
|
|
|
### Fix Task
|
|
|
|
```
|
|
TaskCreate(
|
|
subject: "Fix root cause: {root_cause_summary}",
|
|
activeForm: "Implementing fix",
|
|
description: "Address root cause, add defense-in-depth validation. See defense-in-depth.md",
|
|
metadata: { debugStage: "fix", rootCause: "{root_cause}",
|
|
priority: "P1", effort: "20m" },
|
|
addBlockedBy: ["{analyze-task-id}"]
|
|
)
|
|
```
|
|
|
|
### Verify Task
|
|
|
|
```
|
|
TaskCreate(
|
|
subject: "Verify fix with fresh evidence",
|
|
activeForm: "Verifying fix",
|
|
description: "Run tests, check build, confirm issue resolved. NO CLAIMS WITHOUT EVIDENCE. See verification.md",
|
|
metadata: { debugStage: "verify", priority: "P1", effort: "5m" },
|
|
addBlockedBy: ["{fix-task-id}"]
|
|
)
|
|
```
|
|
|
|
## Parallel Evidence Collection
|
|
|
|
For multi-source investigations, spawn parallel collection agents:
|
|
|
|
```
|
|
// Parallel — no blockedBy between them
|
|
TaskCreate(subject: "Collect CI/CD pipeline logs",
|
|
metadata: { debugStage: "collect", source: "ci",
|
|
agentIndex: 1, totalAgents: 3, priority: "P1" })
|
|
|
|
TaskCreate(subject: "Collect application server logs",
|
|
metadata: { debugStage: "collect", source: "server",
|
|
agentIndex: 2, totalAgents: 3, priority: "P1" })
|
|
|
|
TaskCreate(subject: "Query database for anomalies",
|
|
metadata: { debugStage: "collect", source: "db",
|
|
agentIndex: 3, totalAgents: 3, priority: "P1" })
|
|
|
|
// Analyze blocks on ALL collection completing:
|
|
TaskCreate(subject: "Analyze root cause from collected evidence",
|
|
addBlockedBy: ["{ci-id}", "{server-id}", "{db-id}"])
|
|
```
|
|
|
|
## Task Lifecycle
|
|
|
|
```
|
|
Assess: pending → in_progress → completed (scope + impact identified)
|
|
Collect: pending → in_progress → completed (evidence gathered)
|
|
Analyze: pending → in_progress → completed (root cause identified)
|
|
Fix: pending → in_progress → completed (fix implemented)
|
|
Verify: pending → in_progress → completed (fresh verification evidence)
|
|
```
|
|
|
|
### Re-Investigation Cycle
|
|
|
|
When fix doesn't resolve the issue → new analyze-fix-verify cycle:
|
|
|
|
```
|
|
TaskCreate(subject: "Re-analyze: fix attempt {N} failed",
|
|
addBlockedBy: ["{verify-task-id}"],
|
|
metadata: { debugStage: "analyze", cycle: 2, priority: "P1" })
|
|
```
|
|
|
|
Limit to 3 cycles. After cycle 3 → question architecture (systematic-debugging.md Phase 4.5).
|
|
|
|
## Integration with Cook/Planning
|
|
|
|
Debug tasks are **separate from** cook/planning phase tasks.
|
|
|
|
**When cook spawns debugger:**
|
|
1. Cook encounters failing tests → creates debug pipeline tasks
|
|
2. Debug pipeline executes (assess → collect → analyze → fix → verify)
|
|
3. All debug tasks complete → cook marks phase debugging as done
|
|
4. Cook proceeds to next phase
|
|
|
|
## Report Sync-Back
|
|
|
|
After investigation completes, write diagnostic report per reporting-standards.md. Report persists as the "source of truth" for cross-session reference (tasks are session-scoped only).
|
|
|
|
## Error Handling
|
|
|
|
If `TaskCreate` fails: log warning, continue with sequential debugging. Tasks add visibility and coordination, not core functionality.
|