debugging

# 🔧 Debugging Skill > **"Hypothesize, test, learn, repeat."** Debug problems methodically. Track hypotheses, test systematically, converge on root causes. ## Purpose Debug problems methodically. Track hypotheses, document tests, record what you learn, and converge on root causes. ## When to Use - Something isn't working as expected - Mysterious behavior needs explanation - Performance problems need diagnosis - "Works on my machine" situations ## The Debugging Loop ``` OBSERVE → HYPOTHESIZE → TEST → LEARN → (repeat or) → FIX ``` ### Terminal States - `FIX` — Bug resolved - `WONTFIX` — Intentional behavior - `DEFER` — Not addressing now ## Protocol ### Observation Phase Before guessing, gather facts: ```yaml observation: symptom: "What's the observable problem?" context: "When does it happen?" expected: "What should happen instead?" evidence: - "Error message (exact text)" - "Logs showing the issue" - "Steps to reproduce" constraints: - "What we know for sure" - "What we've already ruled out" ``` ### Hypothesis Tracking ```yaml hypothesis: id: "hyp-001" claim: "The bug is caused by X" confidence: "high|medium|low" if_true: - "We would expect to see..." - "Changing X should fix it" test: action: "What to try" expected: "What we expect if hypothesis is correct" result: status: "confirmed|refuted|inconclusive" observation: "What actually happened" learned: "What this tells us" ``` ### Test Documentation ```yaml test: id: "test-001" hypothesis: "hyp-001" action: "What we did" before: state: "System state before test" after: state: "System state after test" result: "confirmed|refuted|inconclusive" learned: "What we now know" ``` ## Schemas ### Observation Schema | Field | Required | Purpose | |-------|----------|---------| | `symptom` | ✓ | Observable problem | | `expected` | ✓ | What should happen | | `error_message` | | Exact error text | | `logs` | | Relevant log entries | | `steps_to_reproduce` | | How to trigger | | `constraints` | | Known facts | | `ruled_out` | | Eliminated possibilities | ### Hypothesis Schema | Field | Required | Purpose | |-------|----------|---------| | `id` | ✓ | Unique identifier | | `claim` | ✓ | What you think is wrong | | `test` | ✓ | How to validate | | `confidence` | | high/medium/low | | `if_true` | | Expected observations | | `result` | | Test outcome | | `learned` | | Insight gained | ### Test Schema | Field | Required | Purpose | |-------|----------|---------| | `id` | ✓ | Unique identifier | | `hypothesis` | ✓ | Which hypothesis | | `action` | ✓ | What was tried | | `result` | ✓ | confirmed/refuted/inconclusive | | `before` | | State before | | `after` | | State after | | `learned` | | Insight | ## Core Files | File | Purpose | |------|---------| | `DEBUG.yml` | Current debugging session | | `HYPOTHESES.md` | All hypotheses and their status | | `TESTS.md` | Test log | | `ROOT_CAUSE.md` | Final analysis | ## Commands | Command | Action | |---------|--------| | `DEBUG [symptom]` | Start debugging session | | `OBSERVE [fact]` | Record observation | | `HYPOTHESIZE [claim]` | Propose hypothesis | | `TEST [action]` | Document test | | `LEARN [insight]` | Record what you learned | | `ROOT-CAUSE [explanation]` | Document root cause | ## The Scientific Method for Bugs 1. **Observe**: What exactly is happening? 2. **Question**: Why might this be happening? 3. **Hypothesize**: Form testable explanation 4. **Predict**: What would we see if hypothesis is true? 5. **Test**: Try to confirm or refute 6. **Analyze**: What did we learn? 7. **Iterate**: New hypothesis or fix ## Debugging Techniques ### Binary Search Narrow down where the bug lives. Use when the bug is somewhere in a large space. ```yaml technique: binary_search steps: - "Find a known good state" - "Find a known bad state" - "Check the middle" - "Repeat until found" ``` ### Rubber Duck Explain the problem in detail. Use when stuck and need fresh perspective. Write detailed observation in DEBUG.yml — forces you to articulate assumptions. ### Minimal Reproduction Simplify until bug is isolated. Use when complex system with unclear cause. ### Git Bisect Find the commit that introduced bug. Use when bug is a regression. ### Print Debugging Add logging to trace execution. Use when you need to understand flow. ## Working Set Always include in context: - `DEBUG.yml` - `HYPOTHESES.md` ## Integration | Direction | Skill | Relationship | |-----------|-------|--------------| | ← | [play-learn-lift](../play-learn-lift/) | Debugging IS learning | | → | [session-log](../session-log/) | Log all debugging activities | | → | [research-notebook](../research-notebook/) | Complex bugs need research | | → | [honest-forget](../honest-forget/) | Compress debugging wisdom | | ↔ | [adventure](../adventure/) | Debugging IS adventure | | ↔ | [room](../room/) | Debug sessions are rooms | | ↔ | [card](../card/) | Git Goblin 🧌, Index Owl 🦉 companions |