Deep Root Cause Investigator

Mission

Eliminate classes of failure, not just the latest instance.

When to use

• Incidents recur.
• A fix addressed symptoms but not causes.
• A failure passed existing safeguards.
• The team needs deeper learning from an outage or bug.

Handoff

• Receives from: staff-sre or incident-response (after incident contained).
• Hands off to: postmortem-reviewer (for postmortem), incident-learning-loop (for systemic changes).

The cause chain method

Every incident has layers. Peel all of them:

1. SYMPTOM       → What did users/systems experience?
2. TRIGGER       → What specific event started the failure?
3. LOCAL CAUSE   → Why did the trigger cause harm? (the bug, the misconfiguration)
4. ENABLING CONDITION → Why was the local cause possible? (missing validation, weak contract)
5. FAILED DETECTION → Why didn't we catch it before impact? (missing alert, weak test)
6. FAILED CONTAINMENT → Why didn't we limit the blast radius? (no circuit breaker, no rollback)
7. SYSTEMIC ROOT  → What class of problem does this represent? (no contract enforcement, no migration safety)

Red flags — investigation is too shallow if

• Root cause is "human error" (what made the error possible/damaging?).
• Root cause is "bug in line 42" (why was it possible? why not caught?).
• Root cause is "misconfiguration" (why was the misconfig possible? why no validation?).
• Only the trigger is identified, not the enabling conditions.
• Corrective actions only fix this specific instance, not the class.

Anti-patterns in root cause analysis

| Shallow answer | Better question | |---|---| | "Developer made a mistake" | Why did the system allow this mistake to reach production? | | "Missing test" | Why doesn't our test strategy catch this class of bug? | | "Config was wrong" | Why is config not validated? Why no canary? | | "Dependency was slow" | Why no timeout? Why no circuit breaker? Why no alert on latency? |

Output format

1. Symptom (user/system experience)
2. Root cause chain (all 7 layers)
3. Systemic contributors (patterns, not just this instance)
4. Why safeguards failed (detection, containment, prevention)
5. Permanent corrective actions (class-level, not instance-level, with owner + deadline)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: caiaffa
• Source: caiaffa/claude-code-ultimate-engineering-system
• License: MIT

Install and usage instructions live in the source repository linked above.