hypothesis-debugging
Use when debugging bugs, test failures, or unexpected behavior where the root cause is not immediately obvious or previous attempts failed. Applicable when multiple root causes are possible, symptoms are intermittent, or systematic isolation is needed.
ioma8 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add ioma8/hypothesis-debugging --skill hypothesis-debugging技能说明
name: hypothesis-debugging description: Use when debugging bugs, test failures, or unexpected behavior where the root cause is not immediately obvious or previous attempts failed. Applicable when multiple root causes are possible, symptoms are intermittent, or systematic isolation is needed.
Hypothesis Debugging
Overview
Debug by forming specific, testable hypotheses, testing them one at a time, and recording every result in HYPOTHESES.csv. Each hypothesis must be precise enough that a single experiment proves or disproves it. Continue the loop until the root cause is found and validated.
When to Use
- Bug you can reproduce but can't explain
- Test failure with no obvious cause
- Intermittent / non-deterministic failures
- Multiple possible root causes — isolate systematically
- Previous debugging attempts failed — need structured approach
When NOT to use: Blatant syntax errors, import mistakes, and trivial typos visible at a glance. For those, fix directly.
The Hypothesis-Debugging Loop
This is the core process. Follow it in order. DO NOT skip any step.
digraph hypothesis_loop {
rankdir=TB;
node [shape=box, style=filled, fillcolor="#e8f0fe"];
start [label="Bug / test failure\nreported", shape=ellipse, fillcolor="#fff3e0"];
read [label="1. Read to understand\nsystem (not find bug)", fillcolor="#e3f2fd"];
read -> form;
form [label="2. Form ONE specific\ntestable hypothesis", fillcolor="#e3f2fd"];
form -> record_h;
record_h [label="3. Record hypothesis\nin HYPOTHESES.csv", fillcolor="#e3f2fd"];
record_h -> test;
test [label="4. Execute ONE\nsurgical test", fillcolor="#e3f2fd"];
test -> record_c;
record_c [label="5. Record conclusion\nin HYPOTHESES.csv", fillcolor="#e3f2fd"];
record_c -> decide;
decide [label="6. Root cause\nfound and proved?", shape=diamond, fillcolor="#fff3e0"];
decide -> present [label="Yes", color="green"];
decide -> read [label="No — new\nhypothesis", color="red"];
present [label="Present validated\nroot cause", shape=ellipse, fillcolor="#c8e6c9"];
start -> read;
}
Quick Reference
| Step | Action | Output |
|---|---|---|
| 1 | Read codebase to understand SYSTEM (not find bug) | Expected vs actual behavior gap |
| 2 | Form ONE specific, testable hypothesis | A guess about WHY the gap exists |
| 3 | Record in HYPOTHESES.csv | Row with hypothesis + test, empty conclusion |
| 4 | Execute ONE surgical test | Clear result: proved or disproved |
| 5 | Record conclusion in HYPOTHESES.csv | proved / disproved / need more info |
| 6 | Found and proved? STOP. Else → loop to Step 1 | Validated root cause or next hypothesis |
Step 1: Read to Understand the System
Read the codebase, tests, error messages, logs, and config. Your goal is to understand the system — what it should do and what it actually does — NOT to find the bug.
Understand:
- Expected behavior: What does the test/spec say should happen?
- Actual behavior: What does the output show? Reproduce the failure.
- System structure: Components, data flow, inputs/outputs, interfaces.
If you spot a potential bug while reading, do NOT act on it yet. Note it mentally. It will inform your hypothesis in Step 2.
Step 2: Form Exactly One Hypothesis
Based on ALL available information, make the single most probable, specific, testable hypothesis about the root cause.
A hypothesis is a guess about WHY the gap exists between expected and actual behavior. It is NOT a restatement of what you observed in the code.
| Criterion | Good | Bad |
|---|---|---|
| Specific | "The cache doesn't invalidate on writes" | "Something is wrong with caching" |
| Testable | "A cache-miss counter would increase on every write" | "The architecture is flawed" |
| Probable | Evidence points to this component | Random guess with no support |
Step 3: Record Hypothesis in HYPOTHESES.csv
Append a row to HYPOTHESES.csv in the project root:
hypothesis,test,conclusion,notes
"Your specific testable hypothesis","One surgical test that will prove or disprove it",, ← leave conclusion empty
NEVER skip this file. It is your audit trail. Without it you will repeat tests and lose evidence.
Step 4: Execute One Surgical Test
Run ONE test, add ONE logging statement, or make ONE probe that directly tests the hypothesis. NEVER test multiple hypotheses at once.
The test must:
- Test ONLY this hypothesis
- Produce a clear result: proved or disproved
- Be the MINIMUM work needed to test it
Step 5: Record the Conclusion
Update HYPOTHESES.csv with the result:
| Conclusion | Meaning |
|---|---|
| proved | Evidence confirms this IS the root cause |
| disproved | Evidence rules this out as the root cause |
| need more info | Test was inconclusive — note what's missing |
Step 6: Decide
- Root cause proved? → STOP. Present the root cause to the user.
- Not yet found? → Return to Step 1. Use the new knowledge from your test to form the next, more informed hypothesis.
HYPOTHESES.csv Format
Create this file in the project root. Every hypothesis and its result lives here.
hypothesis,test,conclusion,notes
"The cache isn't invalidated on write","Add cache-miss counter before and after write","disproved","Cache hit rate unchanged — cache IS being invalidated"
"Tax calculated on undiscounted subtotal","Run test with taxable=subtotal-discount","proved","Root cause: line 33 in shopping_cart.py"
"The filter skips odd IDs","Test filter with [1,2,3,4]","proved","Root cause: modulo check uses `id % 2 == 0` instead of `id % 2 == 1`"
Rows with empty conclusion = hypotheses still pending. Rows with proved = validated root causes. Rows with disproved = eliminated possibilities.
Before vs After
Without Hypothesis Debugging (jump to fix)
1. Read shopping_cart.py
2. Read test_shopping_cart.py
3. Se
阅读完整来源 ↗