Debugging Methodology

---
name: debugging-methodology
description: Systematic root cause analysis for production and development bugs. Hypothesis-driven debugging — never guess-and-check.
category: test
applies-to: [claude, gemini, cursor, copilot, any]
version: 1.0.0
---

## Overview

Random code changes in response to errors are not debugging — they're noise generation. This skill enforces a systematic, hypothesis-driven approach: understand the problem, form a hypothesis, test it, confirm the root cause, then fix.

AI agents often cycle through random fixes until something "works." This skill prevents that.

## When to Use

- Any time a test fails unexpectedly
- Any time you encounter an error or exception
- When behavior differs between environments
- When performance degrades unexpectedly

## Process

### Step 1: Reproduce Reliably

1. Before doing anything else: **reproduce the bug reliably**. If you can't reproduce it, you can't fix it.
2. Write a failing test that captures the bug — this becomes your regression test.
3. Note the exact conditions that trigger the bug: inputs, environment, sequence of actions.

**Verify:** You can trigger the bug on demand.

### Step 2: Understand Before Diagnosing

4. Read the full error message — not just the first line.
5. Read the stack trace from bottom to top — the root cause is usually near the bottom.
6. Identify: *What was the program trying to do? What happened instead?*

**Verify:** You can explain the bug in one sentence without using the word "error."

### Step 3: Form a Hypothesis

7. Based on what you know, form a specific hypothesis: *"I think the bug is X because Y."*
8. The hypothesis must be **falsifiable** — you can design a test that proves or disproves it.
9. Do not start making code changes until you have a hypothesis.

**Verify:** Your hypothesis is specific enough to design a test for.

### Step 4: Test the Hypothesis

10. Add targeted logging or a targeted test that confirms or refutes the hypothesis.
11. Run it. Read the output carefully.
12. If the hypothesis is **wrong**: update your understanding, form a new hypothesis, repeat.
13. If the hypothesis is **right**: you've found the root cause.

**Verify:** Root cause is confirmed by evidence, not assumed.

### Step 5: Fix the Root Cause (Not the Symptom)

14. Fix the root cause — not the symptom. Suppressing an error message is not a fix.
15. Make the minimum change that fixes the root cause.
16. Run the failing test you wrote in Step 1 — it should now pass.
17. Run the full test suite — no regressions.

**Verify:** The specific failing test now passes. Full suite still passes.

### Step 6: Prevent Recurrence

18. If the bug wasn't caught by existing tests: add a test that would have caught it.
19. If the bug was caused by a bad assumption: document the assumption or add a guard.
20. Consider: does this class of bug exist elsewhere in the codebase?

## Common Rationalizations (and Rebuttals)

| Excuse | Rebuttal |
|--------|----------|
| "Let me just try this and see" | Random changes produce random results. Form a hypothesis first. |
| "It must be a framework bug" | It's almost never the framework. Prove it before blaming it. |
| "Works on my machine" | Environment differences are root causes. Find them. Don't dismiss them. |
| "I'll add a try/catch" | That hides the bug. Find and fix the root cause. |

## Red Flags

- Making code changes before understanding the bug
- Adding try/catch to silence errors without investigating root cause
- "I'll try this and see if it helps"
- Assuming the bug is in a dependency before proving it
- Fixing the symptom (error message) rather than the cause

## Verification

- [ ] Bug reproducible on demand
- [ ] Root cause identified (not just symptom)
- [ ] Fix targets root cause, not symptom
- [ ] Reproduction test written and now passes
- [ ] Full test suite passes with no regressions
- [ ] Regression test added to prevent future occurrence

## References

- [test-driven-development skill](../test-driven-development/SKILL.md)
- [observability skill](../observability/SKILL.md)