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:

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

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

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

Hypothesis Schema

Test Schema

Core Files

Commands

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.

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