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

Accept the following inputs:

• bug-description-or-error — What's failing? Error messages, symptoms
• --deep (optional flag) — If present, skip triage and go directly to deep track (jump to Phase 2 deep track)

Extract from the input 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?

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:

• Ask the user for more context
• 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:

### 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 to the user:

• Summarize the bug and your initial hypothesis
• Recommend quick or deep track with justification
• Prompt the user to choose: "Quick track (Recommended)" / "Deep 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 | See references/python-debugging.md | | TypeScript / JavaScript | See references/typescript-debugging.md | | Other / Multiple | See the General Debugging Reference below |

Always also consult the General Debugging Reference 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:

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 code exploration (from the core-tools package):

For each focus area, investigate:

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

1. Synthesize exploration results:
2. Collect findings from all explorations
3. Identify convergence (multiple areas pointing to same root cause)
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 bug investigation:

For each hypothesis, test it in parallel:

Provide:

• Bug context: description of the bug and error
• Hypothesis to test: the specific hypothesis
• Test plan with concrete steps (e.g., run this test, check git blame, trace data flow)
• Request a report with verdict (confirmed/rejected/inconclusive), evidence, and recommendations

Launch investigations in parallel when they test independent hypotheses.

1. Evaluate results:
2. Update hypothesis journal with each investigation'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:
2. Present all findings to the user
3. Share the hypothesis journal
4. Prompt the user to choose: "Continue investigating", "Try a different angle", "Provide more context"

Phase 4: Fix & Verify

Goal: Fix the root cause and prove the fix works.

4.1 Design the Fix

Before writing any code:

1. Explain the root cause — state clearly what's wrong and why
2. **Explain the