🔧 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

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.

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	Debugging IS learning
→	session-log	Log all debugging activities
→	research-notebook	Complex bugs need research
→	honest-forget	Compress debugging wisdom
↔	adventure	Debugging IS adventure
↔	room	Debug sessions are rooms
↔	card	Git Goblin 🧌, Index Owl 🦉 companions