| type | skill |
| lifecycle | stable |
| inheritance | inheritable |
| name | hypothesis-driven-debugging |
| description | Investigate build failures, test errors, runtime crashes, or unexpected behavior through systematic minimal reproduction, multi-hypothesis testing, and evidence-based verification. Use when asked to "debug", "investigate a failure", "find root cause", "troubleshoot", "fix a failing test", or "diagnose an issue". Always re-run builds and tests after changes. |
| applyTo | **/*debug*,**/*bug*,**/*error*,**/*fix* |
| tier | standard |
| currency | 2026-04-22T00:00:00.000Z |
Hypothesis-Driven Debugging
Apply the scientific method to debugging: observe, hypothesize, experiment, conclude. No trial-and-error.
When to Use
- Test failures, build errors, runtime crashes, performance regressions
- Intermittent or environment-specific failures
- Any situation where the root cause is not immediately obvious
Core Principles
- Always start with a minimal reproduction
- Form at least 3 competing hypotheses
- Verify hypotheses one at a time with evidence
- Re-run the project's build and test commands after every change
Process
Step 1: Observe and Reproduce
Create the smallest possible reproduction:
- Capture the failure: exact error message, stack trace, unexpected output
- Detect the environment: discover the project's runtime, build system, and config by scanning for build/dependency files in the repo
- Determine: deterministic or intermittent?
- Isolate: remove unrelated code and dependencies until you have the minimal failing case
Document:
File/Component: [path]
Command: [detect from project's build/test config]
Expected vs Actual: [describe]
Deterministic?: [yes/no — if no, rate: X/10]
Step 2: Form 3+ Hypotheses
Always form at least 3 competing hypotheses to prevent anchoring.
For each, record: Theory | Supporting evidence | Verification plan | Fix approach if confirmed
Generation tips:
- Consider different layers: input validation, business logic, infrastructure, configuration
- What changed recently: code, dependencies, environment, data?
- Timing/ordering issues: race conditions, initialization order, async behavior?
- Check assumptions: are inputs matching expected types/ranges/formats?
Step 3: Verify Systematically
Test hypotheses one at a time, starting with the most likely or easiest to verify:
| Technique | When to Use |
|---|
| Code instrumentation | Add temporary debug output at key decision points |
