Hypothesis-Driven Debugging

Hypothesis-Driven Debugging

A four-phase loop that turns debugging from "try random fixes and hope" into a disciplined investigation. Each phase has a goal, hard rules, and a rationalization table for the excuses an agent will invent to skip it.

The core principle: you may not write a fix until you have evidence that your hypothesis is correct. Guessing is not debugging.

When to Use

• A test fails and the cause is not immediately obvious
• The same bug has been "fixed" twice and came back
• The agent tried a fix that didn't work — stop it from trying another
• A crash or error message you haven't seen before
• Performance regression with no obvious culprit
• Behavior differs between environments (local vs CI, dev vs prod)
• The agent is stuck in a loop, applying the same wrong fix

When NOT to Use

• Typos, missing imports, or syntax errors — just fix them
• Build failures with an obvious single-line cause
• Compiler/linter messages that tell you exactly what and where
• You already know the root cause and just need to write the fix

If the bug survived one fix attempt, switch to this skill immediately.

The Debug Loop

  OBSERVE  ──▶  HYPOTHESIZE  ──▶  EXPERIMENT  ──▶  CONCLUDE
     │              │                  │               │
     ▼              ▼                  ▼               ▼
  Gather          List 3-5         One minimal       Root cause
  symptoms,       possible         test per          confirmed
  reproduce       causes +         hypothesis,       or loop
  reliably        evidence         max 5 lines       back
     │              │                  │               │
     └──────────────┴──────────────────┴───────────────┘
              write everything to DEBUG.md

Hard rules:

1. Everything gets written to DEBUG.md. Context compaction will eat your reasoning if it only lives in the conversation.
2. You may not write fix code during Observe, Hypothesize, or Experiment.
3. You may not skip Hypothesize. "I think I know what it is" is a hypothesis — write it down and test it like the others.
4. Each experiment changes at most 5 lines. If your experiment needs more, your hypothesis is too vague — split it.

Phase 1: OBSERVE

Goal. Collect raw facts. Reproduce the bug. Separate what you know from what you assume.

Steps.

1. Reproduce the bug. Get the exact error message, stack trace, or wrong output. If you cannot reproduce it, that is your first finding.
2. Find the minimal reproduction. Strip away unrelated code until the bug still appears.
3. Record the environment: OS, runtime version, dependencies, config.
4. Note what does work. The boundary between working and broken is where the bug lives.
5. Write all observations to DEBUG.md under ## Observations.

Exit criteria.

• Bug reproduced (or documented as non-reproducible with conditions)
• Exact error message or wrong behavior recorded
• Minimal reproduction identified
• Observations written to DEBUG.md

Common Rationalizations

Phase 2: HYPOTHESIZE

Goal. Generate 3-5 possible root causes. For each, list supporting and conflicting evidence from Phase 1. Rank by likelihood.

Steps.

1. List 3-5 hypotheses. Not 1. Not "I think it's X." Three minimum. Think across categories:
   • Data: wrong input, missing field, type mismatch, encoding
   • Logic: wrong condition, off-by-one, race condition, wrong order
   • Environment: config, version, dependency, permissions
   • State: stale cache, leaked state, initialization order
2. For each hypothesis, write:
   • Supports: evidence from observations that backs this theory
   • Conflicts: evidence that argues against it
   • Test: the minimal experiment that would prove or disprove it
3. Mark the ROOT HYPOTHESIS — the one with supporting evidence and no conflicting evidence. If multiple qualify, pick the easiest to test.
4. Write everything to DEBUG.md under ## Hypotheses.

Example format in DEBUG.md:

## Hypotheses

### H1: Race condition in session middleware (ROOT HYPOTHESIS)
- Supports: only happens under concurrent requests, timing-dependent
- Conflicts: none yet
- Test: add mutex lock around session read, check if bug disappears

### H2: Stale cache returning expired token
- Supports: works after restart (cache cleared)
- Conflicts: cache TTL is 5min, bug appears within 30s
- Test: disable cache, reproduce

### H3: Wrong env variable in CI
- Supports: works locally, fails in CI
- Conflicts: env diff shows identical values
- Test: print actual runtime value in CI logs

Exit criteria.

• At least 3 hypotheses written
• Each has supporting/conflicting evidence
• Each has a specific, minimal test
• ROOT HYPOTHESIS identified
• All written to DEBUG.md

Common Rationalizations