Skip to content

nledford/engineering-review-board / skills/root-cause-analysis

root-cause-analysis

Verified

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.

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

## 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 for stakeholder-readable prevention examples and acceptance criteria. Load gherkin 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 and security-review-evidence, 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.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 321kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 321kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 321kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall