Claude-Code-Workflow/.codex/skills/ccw-loop-b/workers/worker-debug.md

Worker: DEBUG

Problem diagnosis worker. Hypothesis-driven debugging with evidence tracking.

Purpose

• Locate error source and understand failure mechanism
• Generate testable hypotheses ranked by likelihood
• Collect evidence and evaluate against criteria
• Document root cause and fix recommendations

Preconditions

• Issue exists (test failure, bug report, blocked task)
• state.status === 'running'

Mode Detection

const debugPath = `${progressDir}/debug.md`
const debugExists = fs.existsSync(debugPath)

const debugMode = debugExists ? 'continue' : 'explore'

Execution

Mode: Explore (First Debug)

Step E1: Understand Problem

// From test failures, blocked tasks, or user description
const bugDescription = state.skill_state.findings?.[0]
  || state.description

Step E2: Search Codebase

const searchResults = mcp__ace_tool__search_context({
  project_root_path: '.',
  query: `code related to: ${bugDescription}`
})

Step E3: Generate Hypotheses

const hypotheses = [
  {
    id: 'H1',
    description: 'Most likely cause',
    testable_condition: 'What to check',
    confidence: 'high | medium | low',
    evidence: [],
    mechanism: 'Detailed explanation of how this causes the bug'
  },
  // H2, H3...
]

Step E4: Create Understanding Document

Write(`${progressDir}/debug.md`, `# Debug Understanding

**Loop ID**: ${loopId}
**Bug**: ${bugDescription}
**Started**: ${getUtc8ISOString()}

---

## Hypotheses

${hypotheses.map(h => `
### ${h.id}: ${h.description}
- Confidence: ${h.confidence}
- Testable: ${h.testable_condition}
- Mechanism: ${h.mechanism}
`).join('\n')}

## Evidence

[To be collected]

## Root Cause

[Pending investigation]
`)

Mode: Continue (Previous Debug Exists)

Step C1: Review Previous Findings

const previousDebug = Read(`${progressDir}/debug.md`)
// Continue investigation based on previous findings

Step C2: Apply Fix and Verify

// If root cause identified, apply fix
// Record fix in progress document

Output Format

WORKER_RESULT:
- action: debug
- status: success
- summary: Root cause: {description}
- files_changed: []
- next_suggestion: develop
- loop_back_to: develop

DETAILED_OUTPUT:
ROOT_CAUSE_ANALYSIS:
  hypothesis: "H1: {description}"
  confidence: high
  evidence: [...]
  mechanism: "Detailed explanation"

FIX_RECOMMENDATIONS:
  1. {specific fix action}
  2. {verification step}

Clarification Mode

If insufficient information:

CLARIFICATION_NEEDED:
Q1: Can you reproduce the issue? | Options: [Yes, No, Sometimes] | Recommended: [Yes]
Q2: When did this start? | Options: [Recent change, Always, Unknown] | Recommended: [Recent change]

Error Handling

Error	Recovery
Insufficient info	Output CLARIFICATION_NEEDED
All hypotheses rejected	Generate new hypotheses
>5 iterations	Suggest escalation