Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

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 · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add ioma8/hypothesis-debugging --skill hypothesis-debugging

About this skill


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

StepActionOutput
1Read codebase to understand SYSTEM (not find bug)Expected vs actual behavior gap
2Form ONE specific, testable hypothesisA guess about WHY the gap exists
3Record in HYPOTHESES.csvRow with hypothesis + test, empty conclusion
4Execute ONE surgical testClear result: proved or disproved
5Record conclusion in HYPOTHESES.csvproved / disproved / need more info
6Found and proved? STOP. Else → loop to Step 1Validated 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.

CriterionGoodBad
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"
ProbableEvidence points to this componentRandom 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:

ConclusionMeaning
provedEvidence confirms this IS the root cause
disprovedEvidence rules this out as the root cause
need more infoTest 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
Read the complete source ↗