after we build · part three · root causes
Root causes — operational and chain-aware
Root cause has two layers. The first is operational — what technically went wrong. The second is chain-aware — which level of the chain should have caught it. Both are labelled. The first fixes the symptom. The second fixes the system.
Operational root causes
requirements — Requirements were missing, ambiguous, or incorrect. The spec was wrong before code was written.
logic-error — Implementation logic was wrong. Right spec, wrong code — off-by-one, wrong operator, missed edge.
testing-gap — Existing tests did not cover the failing scenario. The code was wrong and no test caught it.
data — Bad, missing, or unexpected data. Null in a required field, encoding mismatch, stale cache.
configuration — Environment or application config was wrong. Wrong endpoint, missing flag, expired credential.
dependency — Third-party dependency introduced the issue. Library upgrade, provider API change, external downtime.
unknown — Root cause not determined. On critical/high bugs, triggers a follow-up spike. unknown is a temporary state, not an answer.
Chain-aware root causes
scenario-gap — Code did what was specified. Amigos didn't write a scenario for this case. The amigos session had a hole.
adr-drift — Scenario passed but code violates an architectural decision. The promise slipped.
integration-gap — Two systems specified to work together don't. Technical shaping was thin at the boundary.
observation-mismatch — System works as specified but not as the person needs. The brief had a gap. Most expensive, most instructive.
Over months, these labels accumulate into a map. If 40% of high-severity bugs are scenario-gap, the amigos practice needs a structural change. If 25% are observation-mismatch, the discovery sessions need to go deeper.
The bug tracker is not a list of problems. It is a diagnostic instrument for the chain itself.
Enough to know which chain level is fragile.
Every fixed defect and bug carries the full six-dimension taxonomy — severity, impact, type, environment, area, root cause (operational + chain-aware). The tracker becomes a map of where meaning was lost.