Root Cause Analysis Patterns

RCA patterns from real incidents and build failures. Every entry has a date and context.

2026-03-19: Document the Prevention, Not Just the Fix

Situation: Fixed an Antora xref resolution bug but initially only documented the fix command, not how to prevent recurrence

Context: RCA-2026-03-19-001, Don Quijote xrefs unresolved

The Pattern: Every RCA must answer: (1) What happened, (2) Why it happened, (3) What was fixed, (4) How to PREVENT it. The prevention step is the most valuable — it’s the pattern that goes in the journal.

Principle: A fix without prevention is just firefighting. The RCA format forces you to extract the transferable lesson.

Source: RCA-2026-03-19-001, formalized as RCA template standard

2026-02-26: Attribute Assumptions Break Builds

Situation: Used 10.50.1.100 when the actual attribute was {kvm-ip} — 6 missing attributes broke rendering

Context: RCA-2026-02-26-001, documentation build failure

The Pattern: Assumed attribute names without checking. The fix was simple (grep antora.yml), but the prevention required a mandatory pre-write checklist: verify attributes exist before using them.

Principle: Assumptions are the root cause of most preventable failures. The checklist isn’t bureaucracy — it’s pattern recognition formalized.

Source: RCA-2026-02-26-001