bug-killer

What this skill does

# Bug Killer — Hypothesis-Driven Debugging Workflow

Execute a systematic debugging workflow that enforces investigation before fixes. Every bug gets a hypothesis journal, evidence gathering, and root cause confirmation before any code changes.

**CRITICAL: Complete ALL 5 phases.** The workflow is not complete until Phase 5: Wrap-up & Report is finished. After completing each phase, immediately proceed to the next phase without waiting for user prompts.

## Phase Overview

1. **Triage & Reproduction** — Understand, reproduce, route to quick or deep track
2. **Investigation** — Gather evidence with language-specific techniques
3. **Root Cause Analysis** — Confirm root cause through hypothesis testing
4. **Fix & Verify** — Fix with proof, regression test, quality check
5. **Wrap-up & Report** — Document trail, capture learnings

---

## Phase 1: Triage & Reproduction

**Goal:** Understand the bug, reproduce it, and decide the investigation track.

### 1.1 Parse Context

Extract from `$ARGUMENTS` and conversation context:
- **Bug description**: What's failing? Error messages, symptoms
- **Reproduction steps**: How to trigger the bug (test command, user action, etc.)
- **Environment**: Language, framework, test runner, relevant config
- **Prior attempts**: Has the user already tried fixes? What didn't work?
- **Deep flag**: If `--deep` is present, skip triage and go directly to deep track (jump to Phase 2 deep track)

### 1.2 Reproduce the Bug

Attempt to reproduce before investigating:

1. If a failing test was mentioned, run it:
   ```bash
   # Run the specific test to confirm the failure
   <test-runner> <test-file>::<test-name>
   ```
2. If an error was described, find and trigger it
3. If neither, search for related test files and run them

**Capture the exact error output** — this is your primary evidence.

If the bug cannot be reproduced:
- Ask the user for more context via AskUserQuestion
- Check if it's environment-specific or intermittent
- Note "not yet reproduced" in the hypothesis journal

### 1.3 Form Initial Hypothesis

Based on the error message and context, form your first hypothesis:

```markdown
### H1: [Title]
- Hypothesis: [What you think is causing the bug]
- Evidence for: [What supports this — error message, stack trace, etc.]
- Evidence against: [Anything that contradicts it — if none yet, say "None yet"]
- Test plan: [Specific steps to confirm or reject]
- Status: Pending
```

### 1.4 Route to Track

**Quick-fix signals** (ALL must be true):
- Clear, specific error message pointing to exact location
- Localized to 1-2 files (not spread across the codebase)
- Obvious fix visible from reading the error location
- No concurrency, timing, or state management involved

**Deep-track signals** (ANY one triggers deep track):
- Bug spans 3+ files or modules
- Root cause unclear from the error message alone
- Intermittent or environment-dependent failure
- Involves concurrency, timing, shared state, or async behavior
- User already tried fixes that didn't work
- Generic error message (e.g., "null reference" without clear origin)
- Stack trace points to library/framework code rather than application code

**Present your assessment** via AskUserQuestion:
- Summarize the bug and your initial hypothesis
- Recommend quick or deep track with justification
- Options: "Quick track (Recommended)" / "Deep track" / "Deep track" / "Quick track" — depending on your assessment
- Let the user override your recommendation

**Track escalation rule:** If during quick track execution, 2 hypotheses are rejected, automatically escalate to deep track. Preserve all hypothesis journal entries when escalating.

---

## Phase 2: Investigation

**Goal:** Gather evidence systematically, guided by language-specific techniques.

### 2.1 Load Language Reference

Detect the primary language of the bug's context and load the appropriate reference:

| Language | Reference File |
|----------|---------------|
| Python | `Read ${CLAUDE_PLUGIN_ROOT}/skills/bug-killer/references/python-debugging.md` |
| TypeScript / JavaScript | `Read ${CLAUDE_PLUGIN_ROOT}/skills/bug-killer/references/typescript-debugging.md` |
| Other / Multiple | `Read ${CLAUDE_PLUGIN_ROOT}/skills/bug-killer/references/general-debugging.md` |

Always also load `general-debugging.md` as a supplement when using a language-specific reference.

### 2.2 Quick Track Investigation

For quick-track bugs, investigate directly:

1. **Read the error location** — the file and function where the error occurs
2. **Read the immediate callers** — 1-2 files up the call chain
3. **Check recent changes** — `git log --oneline -5 -- <file>` for the affected files
4. **Update hypothesis** — does the evidence support H1? Add evidence for/against

Proceed to Phase 3 (quick track).

### 2.3 Deep Track Investigation

For deep-track bugs, use parallel exploration agents:

1. **Plan exploration areas** — identify 2-3 focus areas based on the bug:
   - Focus 1: The error site and immediate code path
   - Focus 2: Data flow and state management leading to the error
   - Focus 3: Related subsystems, configuration, or external dependencies

2. **Launch code-explorer agents:**

   Spawn 2-3 code-explorer agents from core-tools:

   ```
   Use Task tool with subagent_type: "agent-alchemy-core-tools:code-explorer"

   Prompt for each agent:
   Bug context: [description of the bug and error]
   Focus area: [specific area for this agent]

   Investigate this focus area in relation to the bug:
   - Find all relevant files
   - Trace the execution/data path
   - Identify where behavior diverges from expected
   - Note any suspicious patterns, recent changes, or known issues
   - Report structured findings
   ```

   Launch agents in parallel for independent focus areas.

3. **Synthesize exploration results:**
   - Collect findings from all agents
   - Identify convergence (multiple agents pointing to same area)
   - Update hypothesis journal with new evidence
   - Form additional hypotheses if evidence warrants (aim for 2-3 total)

Proceed to Phase 3 (deep track).

---

## Phase 3: Root Cause Analysis

**Goal:** Confirm the root cause through systematic hypothesis testing.

### 3.1 Quick Track Root Cause

For quick-track bugs:

1. **Verify the hypothesis:**
   - Read the specific code identified in Phase 2
   - Trace the logic step-by-step
   - Confirm that the hypothesized cause produces the observed error

2. **If confirmed** (Status → Confirmed):
   - Update H1 with confirming evidence
   - Proceed to Phase 4

3. **If rejected** (Status → Rejected):
   - Update H1 with evidence against and reason for rejection
   - Form a new hypothesis (H2) based on what you learned
   - Investigate H2 following Phase 2 quick track steps
   - **If H2 is also rejected → escalate to deep track**
   - Preserve all journal entries, continue with Phase 2 deep track

### 3.2 Deep Track Root Cause

For deep-track bugs:

1. **Prepare hypotheses for testing:**
   - You should have 2-3 hypotheses from Phase 2
   - Each needs a concrete test plan (how to confirm or reject)

2. **Launch bug-investigator agents:**

   Spawn 1-3 bug-investigator agents to test hypotheses in parallel:

   ```
   Use Task tool with subagent_type: "bug-investigator"

   Prompt for each agent:
   Bug context: [description of the bug and error]

   Hypothesis to test: [specific hypothesis]
   Test plan:
   1. [Step 1 — e.g., run this specific test with these arguments]
   2. [Step 2 — e.g., check git blame for this function]
   3. [Step 3 — e.g., trace the data from input to error site]

   Report your findings with verdict (confirmed/rejected/inconclusive),
   evidence, and recommendations.
   ```

   Launch agents in parallel when they test independent hypotheses.

3. **Evaluate results:**
   - Update hypothesis journal with each agent's findings
   - If one hypothesis is confirmed → proceed to Phase 4
   - If all are rejected/inconclusive → apply 5 Whys technique:

     Take the strongest