Hypothesis-Driven Debugging
Generate a structured debugging document that identifies candidate root causes and provides falsification plans for each. The output document instructs a separate execution agent; do not perform the investigation yourself.
Philosophical Foundation
Apply Popperian falsificationism: hypotheses cannot be proven true, only disproven. Design tests that could definitively rule out each hypothesis rather than confirm it. A good falsification test produces a clear negative result if the hypothesis is wrong.
Process
1. Gather Context
Before forming hypotheses, collect:
- Symptom description: What behaviour is observed vs expected?
- Reproduction conditions: When does it occur? Intermittent or consistent?
- Recent changes: Deployments, configuration changes, dependency updates
- Error artefacts: Stack traces, logs, error messages, screenshots
- Environmental factors: OS, runtime versions, network conditions
If information is missing, note gaps in the output document.
2. Form Hypotheses
Generate 1–5 hypotheses ranked by plausibility. Each hypothesis must be:
- Specific: Name the component, function, or interaction suspected
- Falsifiable: A concrete test could disprove it
- Independent: Falsifying one should not automatically falsify others
Common hypothesis categories:
| Category |
Examples |
| State |
Race condition, stale cache, corrupted data |
| Input |
Malformed payload, encoding issue, boundary case |
| Environment |
Missing dependency, version mismatch, resource exhaustion |
| Logic |
Off-by-one, incorrect predicate, missing null check |
| Integration |
API contract violation, timeout, auth failure |
Avoid vague hypotheses ("something wrong with the database"). Pin down the specific failure mode.
3. Design Falsification Plans
For each hypothesis, specify:
- Prediction: If this hypothesis is correct, what observable outcome follows?
- Falsification test: What action would produce a contradicting observation?
- Expected negative result: What outcome would disprove the hypothesis?
- Tooling required: Commands, scripts, or instrumentation needed
- Confidence impact: How decisively would a negative result rule this out?
Prefer tests that are:
- Quick to execute
- Minimally invasive
- Deterministic rather than probabilistic
4. Output Document
Generate a Markdown document following the template in assets/debugging-plan.md. Save to the working directory as debugging-plan-{timestamp}.md.
Quality Criteria
A well-formed debugging plan exhibits:
- Mutual exclusivity: At least one hypothesis should survive if others fail
- Collective exhaustiveness: Hypotheses cover the likely failure space
- Ordered efficiency: Cheapest decisive tests appear first
- Clear success criteria: The executing agent knows when to stop
Anti-Patterns
- Confirmation bias: Designing tests that can only succeed, not fail
- Hypothesis creep: Adding new hypotheses during execution rather than revision
- Coupling: Tests that cannot isolate individual hypotheses
- Vagueness: "Check the logs" without specifying what pattern would falsify
References
references/examples.md: Worked examples of hypothesis-falsification pairs across common debugging scenarios (API timeouts, flaky tests, memory leaks)
1---2name: hypothesis-debugging3description: Structured code debugging through hypothesis formation and falsification planning. Use when diagnosing bugs, unexpected behaviour, or system failures where the root cause is unclear. Produces a hypothesis document for execution by another agent rather than performing the investigation directly. Triggers on requests to debug issues, diagnose problems, investigate failures, or create debugging plans.4---5
6# Hypothesis-Driven Debugging
7
8Generate a structured debugging document that identifies candidate root causes and provides falsification plans for each. The output document instructs a separate execution agent; do not perform the investigation yourself.
9
10## Philosophical Foundation
11
12Apply Popperian falsificationism: hypotheses cannot be proven true, only disproven. Design tests that could definitively rule out each hypothesis rather than confirm it. A good falsification test produces a clear negative result if the hypothesis is wrong.
13
14## Process
15
16### 1. Gather Context
17
18Before forming hypotheses, collect:
19
20- **Symptom description**: What behaviour is observed vs expected?
21- **Reproduction conditions**: When does it occur? Intermittent or consistent?
22- **Recent changes**: Deployments, configuration changes, dependency updates
23- **Error artefacts**: Stack traces, logs, error messages, screenshots
24- **Environmental factors**: OS, runtime versions, network conditions
25
26If information is missing, note gaps in the output document.
27
28### 2. Form Hypotheses
29
30Generate 1–5 hypotheses ranked by plausibility. Each hypothesis must be:
31
32- **Specific**: Name the component, function, or interaction suspected
33- **Falsifiable**: A concrete test could disprove it
34- **Independent**: Falsifying one should not automatically falsify others
35
36Common hypothesis categories:
37
38| Category | Examples |
39|----------|----------|
40| State | Race condition, stale cache, corrupted data |
41| Input | Malformed payload, encoding issue, boundary case |
42| Environment | Missing dependency, version mismatch, resource exhaustion |
43| Logic | Off-by-one, incorrect predicate, missing null check |
44| Integration | API contract violation, timeout, auth failure |
45
46Avoid vague hypotheses ("something wrong with the database"). Pin down the specific failure mode.
47
48### 3. Design Falsification Plans
49
50For each hypothesis, specify:
51
521. **Prediction**: If this hypothesis is correct, what observable outcome follows?
532. **Falsification test**: What action would produce a contradicting observation?
543. **Expected negative result**: What outcome would disprove the hypothesis?
554. **Tooling required**: Commands, scripts, or instrumentation needed
565. **Confidence impact**: How decisively would a negative result rule this out?
57
58Prefer tests that are:
59- Quick to execute
60- Minimally invasive
61- Deterministic rather than probabilistic
62
63### 4. Output Document
64
65Generate a Markdown document following the template in `assets/debugging-plan.md`. Save to the working directory as `debugging-plan-{timestamp}.md`.
66
67## Quality Criteria
68
69A well-formed debugging plan exhibits:
70
71- **Mutual exclusivity**: At least one hypothesis should survive if others fail
72- **Collective exhaustiveness**: Hypotheses cover the likely failure space
73- **Ordered efficiency**: Cheapest decisive tests appear first
74- **Clear success criteria**: The executing agent knows when to stop
75
76## Anti-Patterns
77
78- Confirmation bias: Designing tests that can only succeed, not fail
79- Hypothesis creep: Adding new hypotheses during execution rather than revision
80- Coupling: Tests that cannot isolate individual hypotheses
81- Vagueness: "Check the logs" without specifying what pattern would falsify
82
83## References
84
85- `references/examples.md`: Worked examples of hypothesis-falsification pairs across common debugging scenarios (API timeouts, flaky tests, memory leaks)
majiayu000