methodatlas
Method guideEngineering

Hypothesis-Driven Troubleshooting

A practical method guide: clarify prerequisites and materials, understand the complete process, and look up outputs, pitfalls, and stop criteria.

ComplexityMedium
Time30-240 min
Participants1-6
FormatWorkshop + async
MaturityEstablished
Plan Hypothesis-Driven Troubleshooting
01

Prerequisite

What needs to be finished first

Complete firstClear boundary

Set symptom, affected/unaffected cases, current signals, and safe test boundaries; separate containment from diagnosis.

Without a boundary, cases, periods, or variables become mixed.
Complete firstEvidence access

Precise symptom, architecture and changes, hypothesis board, predictions, safe tests, and evidence log

Missing sources remain visible as uncertainty.
02

Preparation

What needs to be ready before start

Materials

Precise symptom, architecture and changes, hypothesis board, predictions, safe tests, and evidence log

People / roles

Troubleshooting lead · hypothesis owners · operator · system experts · scribe

Pre-read

Set symptom, affected/unaffected cases, current signals, and safe test boundaries; separate containment from diagnosis.

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.

03

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?

04

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-Driven Troubleshooting · working structure
HypothesisMechanismPredictionFalsifierTestFindingStatus
Shared pool exhaustedAdd evidence and rationale.Batch occupies shared poolIsolated pool removes timeoutTimeout persists with isolated poolCompare shared and isolated poolFailure only with shared poolSupported
EU network faultAdd evidence and rationale.Regional packet lossEU loss affects web and mobileMobile remains stableCompare EU web and mobileMobile has no lossWeakened
Web release blocksAdd evidence and rationale.Release blocks requests in browserDirect API worksDirect call also failsBypass web and call APIDirect call failsRejected
  1. 1. Mechanism

    Shared pool exhausted
    Batch occupies shared pool
    EU network fault
    Regional packet loss
    Web release blocks
    Release blocks requests in browser
  2. 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. 3. Falsifier

    Shared pool exhausted
    Timeout persists with isolated pool
    EU network fault
    Mobile remains stable
    Web release blocks
    Direct call also fails
  4. 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. 5. Finding

    Shared pool exhausted
    Failure only with shared pool
    EU network fault
    Mobile has no loss
    Web release blocks
    Direct call fails
  6. 6. Status

    Shared pool exhausted
    Supported
    EU network fault
    Weakened
    Web release blocks
    Rejected

All values are fictional.

Reference · original teaching example

  1. 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. 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. 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. 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. 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

05

Artifact

What comes out at the end

Sketch: what the artifact looks like

Hypothesis-driven TroubleshootingSymptome in prüfbare Hypothesen, erwartete Beobachtungen und informative Tests übersetzen, danach den Wissensstand aktualisieren
Hypothesis-Driven TroubleshootingDas Visual zeigt Symptome, Hypothesen mit erwarteten Beobachtungen, Testplan, Evidenz und Diagnose als gerichteten Troubleshooting-Lernpfad.Troubleshooting als gerichteten Lernpfad führenJede Erklärung bleibt Hypothese, bis ein Test mit erwarteter Beobachtung sie bestätigt, verwirft oder verfeinert.vor jedem Test erwartete Beobachtung notierennach jedem Test Wissensstand aktualisierenSymptomebeobachtbar, reproduzierbar,abgegrenztHypothesis LogHyp.UrsacheErwartungStatusH1Cache staleRefresh behebtverworfenH2DB timeoutLatenz steigtbestätigtH3Deploy diffRollback hilftoffenTestplanhoher Informationswert, geringesRisikoEvidenzBeobachtung aktualisiertHypothesenDiagnosebestätigte Erklärung und nächsterFix
Form

Troubleshooting log with prioritised hypotheses, predictions, discriminating tests, results, and residual uncertainty.

Versioning / ownership

Record date, owner, source state, and review date; preserve prior versions.

Tool alternatives
  • 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

HypothesisMechanismPredictionFalsifierTestFindingStatus
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

06

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

HypothesisMechanismPredictionFalsifierTestFindingStatus
Shared pool exhaustedBatch occupies shared poolIsolated pool removes timeoutTimeout persists with isolated poolCompare shared and isolated poolFailure only with shared poolSupported
EU network faultRegional packet lossEU loss affects web and mobileMobile remains stableCompare EU web and mobileMobile has no lossWeakened
Web release blocksRelease blocks requests in browserDirect API worksDirect call also failsBypass web and call APIDirect call failsRejected
07

Pitfalls

Recognize symptoms and steer against them

Quick overview, the full text is in the matching phase in the flow

  1. Symptom viewDatabase problem is written as symptom.View in phase
  2. Hypothesis spaceTeam pursues only first plausible idea.View in phase
  3. Prediction matrixTests are reinterpreted after results.View in phase
  4. Test resultMultiple restarts destroy diagnostic information.View in phase
  5. Diagnostic findingOne successful test is called full root cause.View in phase
08

Stop criteria

When to pause, resolve prerequisites, or choose another approach

Stop Symptom: Is success/failure measurable and free of causal claims?
Stop Hypotheses: Does each explain affected and unaffected cases?
Stop Predictions: Are predictions recorded before testing and discriminating?
Stop Test: Does test vary exactly the discriminating condition and remain reversible?
Stop Decide: Does leading hypothesis explain all signals with a serious alternative tested?

Method after Praxisgemeinschaft. The method emerged as a widespread practice and is not clearly attributed to a single originator or organization. Curated with 1 sources.

Sources: Hypothesis-Driven Troubleshooting

Flow, timeboxes, and pitfalls are editorially curated practice recommendations based on the listed sources.

Finished the method guide?

Go to the profile for purpose, similar methods, and sources or continue to the next method in the catalog.