bug-killer

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.

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 is 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 did not 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> ``

1. If an error was described, find and trigger it
2. 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:

• Prompt the user for more context
• Check if it is 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:

### 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 did not 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: Prompt the user:

• Summarize the bug and your initial hypothesis
• Recommend quick or deep track with justification
• Options: "Quick track (Recommended)" / "Deep track" or "Deep track (Recommended)" / "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 | |----------|-----------| | Python | Read the python-debugging reference from references/python-debugging.md | | TypeScript / JavaScript | Read the typescript-debugging reference from references/typescript-debugging.md | | Other / Multiple | Use the general debugging guidance below |

Always also apply the general debugging guidance 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 workers:

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

1. Delegate to independent exploration workers:

Delegate to 2-3 read-only exploration workers with distinct focus areas:

``` Each worker receives: Bug context: [description of the bug and error] Focus area: [specific area for this worker]

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 workers in parallel for independent focus areas.

1. Synthesize exploration results:
2. Collect findings from all workers
3. Identify convergence (multiple workers pointing to same area)
4. Update hypothesis journal with new evidence
5. 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:
2. Read the specific code identified in Phase 2
3. Trace the logic step-by-step
4. Confirm that the hypothesized cause produces the observed error

1. If confirmed (Status -> Confirmed):
2. Update H1 with confirming evidence
3. Proceed to Phase 4

1. If rejected (Status -> Rejected):
2. Update H1 with evidence against and reason for rejection
3. Form a new hypothesis (H2) based on what you learned
4. Investigate H2 following Phase 2 quick track steps
5. If H2 is also rejected -> escalate to deep track
6. 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:
2. You should have 2-3 hypotheses from Phase 2
3. Each needs a concrete test plan (how to confirm or reject)

1. Delegate to independent investigation workers:

Delegate to 1-3 investigation workers to test hypotheses in parallel:

``` Each worker receives: 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 workers in parallel when they test independent hypotheses.

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

Take the strongest "inconclusive" finding and ask "why?" iteratively: `` Observed: [what actually happens] Why? -> [first-level cause] Why? -> [second-level cause] Why? -> [root cause] ``

• Form new hypotheses from 5 Whys analysis and repeat investigation

1. If stuck after 2 rounds of investigation: