Set symptom, affected/unaffected cases, current signals, and safe test boundaries; separate containment from diagnosis.
Hypothesis-Driven Troubleshooting
A practical method guide: clarify prerequisites and materials, understand the complete process, and look up outputs, pitfalls, and stop criteria.
Prerequisite
What needs to be finished first
Precise symptom, architecture and changes, hypothesis board, predictions, safe tests, and evidence log
Preparation
What needs to be ready before start
Precise symptom, architecture and changes, hypothesis board, predictions, safe tests, and evidence log
Troubleshooting lead · hypothesis owners · operator · system experts · scribe
Set symptom, affected/unaffected cases, current signals, and safe test boundaries; separate containment from diagnosis.
30–180 minutes per failure; for production-critical events run alongside safe containment.
Prepare a workspace with Symptom · Hypotheses · Predictions · Test · Decide; separate example from live data.
Core question
The one question this method answers
Which competing hypothesis best explains all observed signals, and which safe test discriminates among them most strongly?
Flow
Phases with goal, actions, output and pitfall
Jede Vermutung wird mit einer Prüfung verknüpft, die möglichst viel Information pro Test liefert. Dadurch entsteht eine Reihenfolge, in der die stärksten Hypothesen zuerst unter Druck geraten und die Diagnostik nicht im Kreis läuft. Der Ansatz verbindet Debugging mit sauberer Evidenz.
Hypothesis-Driven Troubleshooting · working structure
Fictional example
Fictional values show the actual method fields.
| Hypothesis | Mechanism | Prediction | Falsifier | Test | Finding | Status |
|---|---|---|---|---|---|---|
| Shared pool exhaustedAdd evidence and rationale. | Batch occupies shared pool | Isolated pool removes timeout | Timeout persists with isolated pool | Compare shared and isolated pool | Failure only with shared pool | Supported |
| EU network faultAdd evidence and rationale. | Regional packet loss | EU loss affects web and mobile | Mobile remains stable | Compare EU web and mobile | Mobile has no loss | Weakened |
| Web release blocksAdd evidence and rationale. | Release blocks requests in browser | Direct API works | Direct call also fails | Bypass web and call API | Direct call fails | Rejected |
1. Mechanism
- Shared pool exhausted
- Batch occupies shared pool
- EU network fault
- Regional packet loss
- Web release blocks
- Release blocks requests in browser
2. Prediction
- Shared pool exhausted
- Isolated pool removes timeout
- EU network fault
- EU loss affects web and mobile
- Web release blocks
- Direct API works
3. Falsifier
- Shared pool exhausted
- Timeout persists with isolated pool
- EU network fault
- Mobile remains stable
- Web release blocks
- Direct call also fails
4. Test
- Shared pool exhausted
- Compare shared and isolated pool
- EU network fault
- Compare EU web and mobile
- Web release blocks
- Bypass web and call API
5. Finding
- Shared pool exhausted
- Failure only with shared pool
- EU network fault
- Mobile has no loss
- Web release blocks
- Direct call fails
6. Status
- Shared pool exhausted
- Supported
- EU network fault
- Weakened
- Web release blocks
- Rejected
All values are fictional.
- 1
Symptom
Symptom view

Goal
Symptom view: Operationalise observed failure and collect Is/Is-Not cases.
Inputs for this step
- Set symptom, affected/unaffected cases, current signals, and safe test boundaries; separate containment from diagnosis.
- Precise symptom, architecture and changes, hypothesis board, predictions, safe tests, and evidence log
Actions
- Operationalise observed failure and collect Is/Is-Not cases.
Output
Symptom view
Operationalise observed failure and collect Is/Is-Not cases.
Quality check
Is success/failure measurable and free of causal claims?
Pitfall
Database problem is written as symptom. State only observable behaviour, scope, and time.
Timing: 10–20 minutes
- 2
Hypotheses
Hypothesis space

Goal
Hypothesis space: Derive several mechanistic explanations from signals, architecture, and changes.
Inputs for this step
- Symptom view
Actions
- Derive several mechanistic explanations from signals, architecture, and changes.
Output
Hypothesis space
Derive several mechanistic explanations from signals, architecture, and changes.
Quality check
Does each explain affected and unaffected cases?
Pitfall
Team pursues only first plausible idea. Add a competing explanation and null hypothesis.
Timing: 10–20 minutes
- 3
Predictions
Prediction matrix

Goal
Prediction matrix: Write observable predictions and falsifying signals for every hypothesis.
Inputs for this step
- Hypothesis space
Actions
- Write observable predictions and falsifying signals for every hypothesis.
Output
Prediction matrix
Write observable predictions and falsifying signals for every hypothesis.
Quality check
Are predictions recorded before testing and discriminating?
Pitfall
Tests are reinterpreted after results. Record expected findings and exclusion rule before execution.
Timing: 10–20 minutes
- 4
Test
Test result

Goal
Test result: Run safest highest-information test, changing one condition at a time.
Inputs for this step
- Prediction matrix
Actions
- Run safest highest-information test, changing one condition at a time.
Output
Test result
Run safest highest-information test, changing one condition at a time.
Quality check
Does test vary exactly the discriminating condition and remain reversible?
Pitfall
Multiple restarts destroy diagnostic information. One change per test; label emergency action separately.
Timing: 15–90 minutes
- 5
Decide
Diagnostic finding

Goal
Diagnostic finding: Update hypotheses against all evidence, record mechanism, and hand over next action/residual uncertainty.
Inputs for this step
- Test result
Actions
- Update hypotheses against all evidence, record mechanism, and hand over next action/residual uncertainty.
Output
Diagnostic finding
Update hypotheses against all evidence, record mechanism, and hand over next action/residual uncertainty.
Quality check
Does leading hypothesis explain all signals with a serious alternative tested?
Pitfall
One successful test is called full root cause. State diagnostic boundary and pass remaining cause question separately.
Timing: 15–30 minutes
Artifact
What comes out at the end
Sketch: what the artifact looks like
Troubleshooting log with prioritised hypotheses, predictions, discriminating tests, results, and residual uncertainty.
Record date, owner, source state, and review date; preserve prior versions.
- Hypothesis and prediction board
- Test/evidence log
- Decision and residual-uncertainty log
hypothesis-driven-troubleshooting-working-template.md
Set subject, evidence, roles, flow, and review.
Hypothesis-Driven Troubleshooting: Worksheet
Question
To be confirmed
Desired outcome
To be confirmed
Scope
Complete run Time: 30–180 minutes per failure; for production-critical events run alongside safe containment.
Complete this worksheet on paper or in your own document during the work.
Preparation for this scope
Method setup
- Materials: Precise symptom, architecture and changes, hypothesis board, predictions, safe tests, and evidence log
- Roles: Troubleshooting lead · hypothesis owners · operator · system experts · scribe
- Advance information: Set symptom, affected/unaffected cases, current signals, and safe test boundaries; separate containment from diagnosis.
- Overall time needed: 30–180 minutes per failure; for production-critical events run alongside safe containment.
- Setup: Prepare a workspace with Symptom · Hypotheses · Predictions · Test · Decide; separate example from live data.
Prepare for the work steps
Symptom: Symptom view
- Set symptom, affected/unaffected cases, current signals, and safe test boundaries; separate containment from diagnosis.
- Precise symptom, architecture and changes, hypothesis board, predictions, safe tests, and evidence log
Hypotheses: Hypothesis space
- Symptom view
Predictions: Prediction matrix
- Hypothesis space
Test: Test result
- Prediction matrix
Decide: Diagnostic finding
- Test result
Hypothesis-Driven Troubleshooting · working structure
| Hypothesis | Mechanism | Prediction | Falsifier | Test | Finding | Status |
|---|---|---|---|---|---|---|
| Shared pool exhausted | ||||||
| EU network fault | ||||||
| Web release blocks |
- Shared pool exhausted: Add evidence and rationale.
- EU network fault: Add evidence and rationale.
- Web release blocks: Add evidence and rationale.
The blank worksheet contains prompts only.
Reference · original teaching example
Symptom: Symptom view
Expected artifact: Symptom view
Operationalise observed failure and collect Is/Is-Not cases.
Entry:
...
- Is success/failure measurable and free of causal claims?
Hypotheses: Hypothesis space
Expected artifact: Hypothesis space
Derive several mechanistic explanations from signals, architecture, and changes.
Entry:
...
- Does each explain affected and unaffected cases?
Predictions: Prediction matrix
Expected artifact: Prediction matrix
Write observable predictions and falsifying signals for every hypothesis.
Entry:
...
- Are predictions recorded before testing and discriminating?
Test: Test result
Expected artifact: Test result
Run safest highest-information test, changing one condition at a time.
Entry:
...
- Does test vary exactly the discriminating condition and remain reversible?
Decide: Diagnostic finding
Expected artifact: Diagnostic finding
Update hypotheses against all evidence, record mechanism, and hand over next action/residual uncertainty.
Entry:
...
- Does leading hypothesis explain all signals with a serious alternative tested?
Open questions and next steps
...
Method guide: https://methodatlas.meierhoff-systems.de/en/methods/hypothesis-driven-troubleshooting/run-sheet
Example output
Concrete filled scenario, fictional example
Fictional example for orientation. Counts and timings describe this case and are not universal requirements.
hypothesis-driven-troubleshooting-beispiel.md
Concrete filled scenario, fictional example
Fictional teaching example: Hypothesis-Driven Troubleshooting · working structure
| Hypothesis | Mechanism | Prediction | Falsifier | Test | Finding | Status |
|---|---|---|---|---|---|---|
| Shared pool exhausted | Batch occupies shared pool | Isolated pool removes timeout | Timeout persists with isolated pool | Compare shared and isolated pool | Failure only with shared pool | Supported |
| EU network fault | Regional packet loss | EU loss affects web and mobile | Mobile remains stable | Compare EU web and mobile | Mobile has no loss | Weakened |
| Web release blocks | Release blocks requests in browser | Direct API works | Direct call also fails | Bypass web and call API | Direct call fails | Rejected |
Pitfalls
Recognize symptoms and steer against them
Quick overview, the full text is in the matching phase in the flow
- Symptom viewDatabase problem is written as symptom.View in phase
- Hypothesis spaceTeam pursues only first plausible idea.View in phase
- Prediction matrixTests are reinterpreted after results.View in phase
- Test resultMultiple restarts destroy diagnostic information.View in phase
- Diagnostic findingOne successful test is called full root cause.View in phase
Symptom view
Database problem is written as symptom.
State only observable behaviour, scope, and time.
Hypothesis space
Team pursues only first plausible idea.
Add a competing explanation and null hypothesis.
Prediction matrix
Tests are reinterpreted after results.
Record expected findings and exclusion rule before execution.
Test result
Multiple restarts destroy diagnostic information.
One change per test; label emergency action separately.
Diagnostic finding
One successful test is called full root cause.
State diagnostic boundary and pass remaining cause question separately.
Stop criteria
When to pause, resolve prerequisites, or choose another approach
Finished the method guide?
Go to the profile for purpose, similar methods, and sources or continue to the next method in the catalog.

