# Root Cause Analysis

> Structured root-cause analysis for recurring failures, incidents, regressions, systemic process gaps, and postmortem-style prevention work. Use after the direct cause of a current symptom is understood; use systematic-debugging first for active failing tests, crashes, or unknown immediate causes.

- Skill: `nledford/root-cause-analysis` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nledford/root-cause-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nledford/root-cause-analysis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nledford (https://skillmd.com/u/nledford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nledford/root-cause-analysis

---


# Root Cause Analysis

Root cause analysis (RCA) identifies the underlying technical, process, and
system factors that allowed a failure to occur or recur. Its goal is durable
prevention, not just the smallest code fix.

## When to Use

Use this skill for:

- Recurring defects, flaky failures, repeated regressions, or incident trends.
- Production or incident-like failures where impact, timeline, and prevention
  matter.
- Customer-impacting behavior where the direct fix is not enough to explain why
  the defect escaped.
- Cross-team, workflow, validation, documentation, release, observability, or
  ownership gaps.
- Postmortem-style analysis after `systematic-debugging` has identified the
  immediate cause of a current symptom.

Do **not** use this as the first response to an active failing test, crash, or
unknown bug. Use `systematic-debugging` first to reproduce the symptom, capture
evidence, and isolate the direct cause.

## RCA Workflow

1. **Define the event**
   - What happened, when, where it was observed, and who/what was affected?
   - Use concrete evidence: test names, commands, route classes, logs, metrics,
     screenshots, traces, or user-visible behavior.
2. **Separate symptom, trigger, root cause, and contributing factors**
   - Symptom: what was observed.
   - Proximate trigger: what activated the failure.
   - Direct cause: the technical mechanism.
   - Contributing factors: why the issue escaped or recurred.
3. **Map expected vs actual controls**
   - Which test, review, type, constraint, migration, observability, or process
     should have caught this?
   - Was the control absent, weak, bypassed, flaky, undocumented, or scoped to
     the wrong layer?
4. **Identify durable prevention**
   - Prefer behavior-oriented regression tests, domain invariant checks,
     stronger validation, clearer ownership, better observability, or documented
     workflow changes over broad rewrites.
5. **Prioritize actions**
   - Separate required fixes from nice-to-have cleanup.
   - Assign follow-ups to the lowest layer that prevents recurrence.

## Techniques

- **5 Whys**: useful for walking from the proximate failure to a process or
  system gap. Stop when the next "why" would become speculative.
- **Fault tree**: useful when multiple independent factors could have caused or
  amplified the failure.
- **Control gap analysis**: useful when prevention depends on repository
  workflows, generated artifacts, schema metadata, feature boundaries, security
  review evidence, or other controls that should have caught the failure.
- **Timeline reconstruction**: useful for incidents, flaky tests, releases, and
  multi-step regressions.

## Output Template

```markdown
## Root Cause Analysis

- Event:
- Impact:
- Evidence reviewed:
- Expected behavior/control:
- Actual behavior/control gap:
- Proximate trigger:
- Direct technical cause:
- Contributing factors:
- Root cause:
- Why existing tests/reviews/checks missed it:
- Corrective actions completed:
- Preventive actions recommended:
- Validation or monitoring needed:
- Remaining risks:
```

## Prevention Considerations

- Prefer repository-owned validation lanes when prevention depends on repeatable
  checks.
- For user-visible behavior, use
  [`behavior-driven-development`](../behavior-driven-development/SKILL.md) for
  stakeholder-readable prevention examples and acceptance criteria. Load
  [`gherkin`](../gherkin/SKILL.md) only when writing a formal `.feature` artifact.
- For code defects, recommend TDD-style regression coverage at the narrowest
  useful layer before or alongside implementation.
- For domain failures, name the affected bounded context and invariant rather
  than describing only tables, routes, or UI widgets.
- For security-sensitive incidents or prevention work, load
  [`security-review`](../security-review/SKILL.md) and
  [`security-review-evidence`](../security-review-evidence/SKILL.md), follow any
  repository security policy that exists, and keep evidence sanitized.

## Guardrails

Do **not**:

- Stop at "human error", "test was wrong", "race condition", or "environment
  issue" without evidence and a control gap.
- Blame individuals; analyze systems, ownership, workflow, validation, and
  technical constraints.
- Recommend broad rewrites when a targeted control prevents recurrence.
- Add process-heavy follow-ups that are not proportional to impact and
  recurrence risk.
- Claim prevention is complete without validation, monitoring, or an explicit
  reason it is not needed.