evidence-driven-debugging

Evidence-Driven Debugging

Overview

The active-debugging companion to investigate-root-cause. Where investigate produces a written hypothesis, evidence-driven-debugging is the workflow for testing that hypothesis with real instrumentation: logs, breakpoints, prints, debugger sessions, runtime probes. The skill exists because the most common debugging-phase failure is the engineer who runs through three or four mental hypotheses without writing anything down, ends up where they started, and can't reconstruct what they tried. Evidence-driven debugging keeps a paper trail. Used inside Phase 3 of investigate-root-cause, but invocable directly when an existing hypothesis just needs runtime testing.

When to Use

• You have a hypothesis from investigate-root-cause and need to test it
• You're debugging in a system that's hard to step through (async, distributed, multi-process)
• You've added logs/prints to test a theory and need to organize what you learn
• A bug only reproduces in a deployed environment, not locally
• You're about to do "let me just add some console.logs" — pause and use this skill to keep them organized

When NOT to Use

• You don't have a hypothesis yet — go to investigate-root-cause Phase 2 first
• The bug is in code you can step through with a debugger and the path is short
• The fix is one line and obvious from reading; debugging instrumentation is overkill

Process

Step 1: State the hypothesis to test

Goal: Be explicit about what runtime evidence will confirm or refute.

Inputs: A hypothesis (from investigate-root-cause Phase 2 or your own prior thinking).

Actions:

1. Write the hypothesis as one sentence: The bug occurs because [X] causes [Y] when [Z].
2. Decide what runtime evidence would confirm it: a value at a specific line, a sequence of events, an absence of an expected log line.
3. Decide what would refute it: the value isn't what you predicted, the sequence is different, the expected event happens but the bug still occurs.