english/.opencode/skills/ck-debug/references/task-management-debugging.md

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.