Turn One Failure Into a Root-Cause Dossier

Choose one Version 1 failure from your test matrix.

If Version 1 had no natural failure, use the clearly labeled fault-injection copy created in Unit 17. Do not rewrite history and claim an injected defect occurred naturally.

Concept flow

A failure becomes a defensible root-cause dossier

Preserve the evidence chain from reproduction through regression rather than rewriting history after the fix.

1. REPRODUCEcapture the failing requirement, input, expected, and actual result
   trace
2. TRACEfollow state until the first divergence
   locate
3. ROOT CAUSEidentify the failed state, operation, or assumption
   correct
4. CONTROLLED CORRECTIONchange the responsible boundary
   verify
5. REGRESSION / DEFENSErerun evidence and explain the repair

Reproduce it first

Document:

requirement:
test case:
input/state:
expected:
actual:
reproduction steps:
environment:

Run it again. If the result cannot be reproduced, do not announce a fix yet. Investigate the conditions that differ.

Build the boundary trace

Example:

raw line
  expected: "2180,95"
  actual:   "2180,95"

parsed record
  expected team=2180 score=95
  actual   team=2180 score=95

aggregation state
  expected total=95
  actual   total=0   <-- first divergence

formatted output
  expected 2180=95
  actual   2180=0

The output is wrong, but the first divergence is aggregation. That narrows the investigation.

Form a falsifiable hypothesis

Weak: something is wrong with the map.

Stronger: the code reads the old total with the wrong key, so every update begins from zero.

A hypothesis should predict what one controlled change will do.

Change one responsible boundary

Avoid fixing five things at once. If the architecture itself caused the defect, the correction may be larger, but state exactly why a structural change is required.

Preserve evidence

Keep Version 1 code or diff, the failing case, trace, hypothesis, and Version 2 change. This is the evidence chain that makes the fix defensible.

Root-cause statement

Write a final statement in this form:

The failure occurred because [specific state/operation/assumption]
at [specific boundary]. It produced [first divergent state], which later
caused [visible symptom]. The correction changes [specific responsibility]
without intentionally changing [unrelated behavior].

Avoid "the bug was in the code." Identify the failed reasoning.