liveBook · Manning

Cause analysis

As explained in Build High Value Software Systems

A systematic process for identifying the underlying causes of a problem or failure rather than addressing only its symptoms.

A restart clears a queue; a retry makes a flaky test pass. Neither explains why the failure happened. Cause analysis investigates recurring or costly failures so the next change addresses the condition that produced them, rather than repeatedly treating the symptom. Before investigating, weigh how often the failure occurs against its cost in time, trust, and risk. Then ask: What allowed it? What would prevent it from recurring? section 8.0 section 8.1

Combine four tools rather than expecting one to tell the whole story:

  • Is/Is Not compares where and when the failure occurs with where and when it does not, narrowing what changed. section 8.2.5
  • 5 Whys traces a chain of explanations, testing each answer with another question. section 8.9
  • A fishbone diagram checks categories of possible causes that the first chain may have missed. section 8.9
  • Pareto analysis ranks failures by frequency so effort goes to the dominant problem first. section 8.9

A notification failure

Suppose emails stop reaching Pro-plan users in the EU after Tuesday’s deploy, while Free-plan and US-East deliveries succeed. That boundary points toward the deploy and the affected onboarding path. A 5 Whys chain reaches a missing field mapping in a migration specification generated from the US schema. A fishbone check then finds two more incorrectly mapped fields and a staging environment that lacks the EU schema. Restarting the service may clear the queue, but it cannot correct those conditions. section 8.2.5

Finish the investigation with countermeasures. Fix the immediate defect, prevent the same class of defect through safer defaults or automated checks, and detect conditions that still escape. For an undersized monetary database column, that could mean a schema migration, a CI schema rule, and a boundary alert. An alert alone is not prevention if someone must keep intervening. Evaluate proposed patches—including AI-generated ones—as hypotheses: does the change remove the cause, or merely hide the failure? Record the evidence and actions in a concise A3 report, and review incidents without blame so people can describe what actually happened. section 8.1 section 8.4 section 8.6 section 13.2

Table 8.3 Countermeasure versus quick-fix evaluation
Change
Type
How to tell
Schema migration prevents invalid data
Countermeasure
The invalid state cannot exist — the database enforces it
Rate limiter caps request volume
Countermeasure
Overload is structurally blocked before it reaches the service
Retry loop hides intermittent failures
Quick fix
The failure still happens; the retry just hides it
Input sanitization works around bad upstream data
Quick fix
The upstream service still sends bad data every time
Updated deployment template with correct defaults
Countermeasure
The standard work changed, future engineers get the right config without thinking about it
Circuit breaker with fallback mode
Countermeasure
The system handles the failure by design, not by luck

Compare proposed changes by whether they block or contain the failure, or leave it happening behind a workaround. section 8.5

How Build High Value Software Systems covers it

How deep it goes
Works through scoping, cause chains, blind-spot checks, prioritization, and fix-prevent-detect countermeasures rather than stopping at a diagnosis.
Examples
Uses an EU notification migration, an undersized monetary column, and a flaky test masked by retries.
What it assumes
Assumes familiarity with software failures, deployments, tests, and CI while introducing the investigation questions and tools.
What you can do after
Practice/perform a cause investigation, test whether a proposed fix prevents recurrence, and document countermeasures for implementation.
How it connects
Links Is/Is Not, 5 Whys, fishbone diagrams, Pareto analysis, countermeasures, and A3 reports.

Also explained in

Compare how 4 books explain cause analysis →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Build High Value Software Systems. The section links point to the parts of the book it draws on.