debug-tracer

Skill: debug-tracer

Purpose

Systematically trace and resolve bugs using hypothesis-driven debugging. Prevents random trial-and-error and ensures the root cause is found, not just the symptom.

Trigger

Use when:

• A bug report needs investigation
• Tests are failing unexpectedly
• Behavior is wrong but the cause is unknown
• "It worked before" situations

Process

Step 1: Reproduce First

Before any investigation, reproduce the bug:

# Document exact reproduction steps:
1. [exact command or action]
2. [expected behavior]
3. [actual behavior]
4. [error message or output]

If you cannot reproduce it, stop. A bug you can't reproduce cannot be safely fixed.

Step 2: Gather Evidence

Collect all available information:

• Full error message and stack trace
• Relevant log output
• When it started occurring (if known)
• What changed recently (git log --oneline -20)
• Environment details if relevant

Step 3: Form Hypotheses

Based on the evidence, list 2-5 hypotheses ranked by likelihood:

## Hypotheses
1. [Most likely] The input validation in X is not handling Y case
2. [Likely] Race condition in async handler Z
3. [Possible] Dependency version mismatch after recent update
4. [Unlikely] Infrastructure/environment issue

Step 4: Test Hypotheses (Cheapest First)

For each hypothesis, starting with the easiest to test:

1. What evidence would confirm or deny this hypothesis?
2. What is the minimal test to check it?
3. Run the test
4. Update hypothesis list based on results

Never fix before confirming hypothesis.

Step 5: Identify Root Cause

Once a hypothesis is confirmed:

• Find the exact line(s) causing the issue
• Understand WHY it causes the issue (not just that it does)
• Check if the same pattern exists elsewhere in the codebase

Step 6: Fix

Apply the minimal fix that addresses the root cause:

• Do not "fix" symptoms
• Do not add defensive code around the bug without fixing it
• The fix should make the reproduction steps work correctly