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'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> ``

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
• Options: "Quick track (Recommended)" / "Deep track" or vice versa 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 | Load references/python-debugging.md from this skill | | TypeScript / JavaScript | Load references/typescript-debugging.md from this skill | | Other / Multiple | Use the general debugging techniques below |

Always also apply general debugging techniques as a supplement when using a language-specific reference.

General Debugging Techniques

Systematic Methods:

• Binary Search for Bugs -- Narrow the problem space by half at each step: identify the full code path, place a diagnostic check at the midpoint, determine which half contains the bug, repeat
• Git Bisect -- Automate binary search through commit history when you know "it used to work"
• Delta Debugging -- Minimize the input that triggers the bug by progressively removing halves
• 5 Whys -- Drill past symptoms to root causes by asking "why?" iteratively until you reach something directly fixable

Reading Stack Traces:

| Element | What It Tells You | |---------|-------------------| | Error type/name | Category of failure (null access, type mismatch, etc.) | | Error message | Specific details about what went wrong | | File path + line number | Where the error was thrown | | Function/method name | What was executing when it failed | | Frame ordering | The call chain that led to the error |

What stack traces cannot tell you:

• Why the wrong value got there (trace backwards)
• When the state became corrupted (may have happened earlier)
• Where in async code the real problem is (async gaps)

Bug Categories:

• Off-by-One -- Check < vs <=, 0-based vs 1-based, inclusive vs exclusive ranges
• Null/Undefined/None -- Uninitialized variables, missing return values, optional fields without guards
• Race Conditions -- Shared mutable state, missing locks, read-then-write without atomicity
• Resource Leaks -- File handles not closed, connections not returned, event listeners not removed
• State Corruption -- Mutation of shared objects, missing deep copies, partial updates

Diagnostic Logging Strategy: Log at decision points and data boundaries:

[ENTRY] function_name called with: key_arg=value
[BRANCH] taking path X because condition=value
[DATA] received from external: summary_of_data
[EXIT] function_name returning: summary_of_result

Investigation Checklist: Before proposing a fix, verify you can answer:

• Can you reproduce the bug reliably?
• What is the expected vs actual behavior?
• Have you identified the specific line(s) causing the issue?
• Do you understand WHY those lines produce the wrong result?
• Is this the root cause, or a symptom of a deeper issue?
• Could this same root cause affect other code paths?

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:
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. Launch exploration agents:

Spawn 2-3 read-only exploration agents (refer to the code-explorer agent from the core-tools package):

Each agent receives:

• Bug context: description of the bug and error
• Focus area: specific area for that agent
• Instructions to find all relevant files, trace execution/data paths, identify where behavior diverges from expected, note suspicious patterns or recent changes, and report structured findings

Launch agents in parallel for independent focus areas.

1. Synthesize exploration results:
2. Collect findings from all agents
3. Identify convergence (multiple agents 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 P