root-cause-tracing
Use when investigating an issue whose origin is unclear, especially when symptoms appear far from the cause. Trigger cues - "bug", "unexpected behavior", "traceback", "why is this happening", "non-deterministic failure". Goal - Trace causality backward to find and validate the true root cause before fixing.
When & Why to Use This Skill
This Claude skill provides a systematic framework for Root Cause Analysis (RCA) and causal debugging. It enables developers and engineers to move beyond surface-level symptoms by tracing causality backward, gathering evidence-based instrumentation, and validating the true origin of complex, non-deterministic failures before applying targeted, minimal-impact fixes.
Use Cases
- Investigating 'Heisenbugs' or intermittent failures that lack clear reproduction steps and appear non-deterministic.
- Tracing the source of production errors where the stack trace or symptoms surface in a different component or service from the actual logic error.
- Conducting formal Root Cause Analysis (RCA) after an incident to identify systemic risks and implement long-term defensive guards.
- Debugging complex data flow issues across multiple microservices to identify exactly where state or data first became invalid.
| name | root-cause-tracing |
|---|---|
| description | Use when investigating an issue whose origin is unclear, especially when symptoms appear far from the cause. Trigger cues - "bug", "unexpected behavior", "traceback", "why is this happening", "non-deterministic failure". Goal - Trace causality backward to find and validate the true root cause before fixing. |
Root Cause Tracing (Causal Debugging Mode)
Goal
Find the origin of the failure, not just where it surfaces. Temporary patches are acceptable for urgent recovery but must include monitoring and follow-up RCA.
Persona
Calm, evidence-first investigator. Flags uncertainty and evidence gaps explicitly.
Process
Phase 1 — Observe the Symptom
- Restate the failure precisely.
- Capture immediate evidence (logs/traces/telemetry, failing conditions, timelines).
- If urgent: apply temporary patch with monitoring and create a follow-up RCA task.
Phase 2 — Gather Context
- Add/inspect instrumentation at the failure site.
- Capture: key variables/inputs, environment/config state, call/data path, recent changes.
- For intermittents: collect multiple samples to identify patterns; avoid hypotheses.
Phase 3 — Trace Backward with Bounded Systemic Scan
3A. Primary Chain (default):
- Follow the strongest-evidence chain (directly logged/observable/reproducible transitions) upstream one link at a time.
- Ask why each upstream condition occurred; stop at earliest invalid state/assumption.
3B. Concurrent Mapping (only if systemic signals present):
Signals: cross-service impact, env/code interaction, correlated alerts across components.
Build a 3–5 factor map (evidence-ranked). For top 1–2 factors, add sentinel checks/instrumentation in parallel.
If the primary chain stalls, pivot to the highest-evidence mapped branch.
Always record missing evidence (“Need upstream audit logs”, “Hardware sensor data absent”).
Phase 4 — Validate
- Form 1–2 concise root-cause hypotheses.
- Reproduce; if non-reproducible, use statistical patterns, fuzzing, controlled input variation.
- Confirm: a fix at this origin removes the failure with no unintended effects.
- Record confidence (e.g., “80%—awaiting config snapshot from host B”).
Phase 5 — Fix + Defenses
- Apply a minimal sufficient change with blast-radius assessment (scope audit: where else can this precondition occur?).
- Add targeted validations/guards to prevent recurrence.
- Escalate breadth (wider refactor/layered defenses) only if evidence shows systemic risk or correlated failures.
Exit Condition
Done when:
- Root cause is identified and validated (or best hypothesis + confidence + missing data listed),
- Fix is applied or clearly defined,
- Minimal recurrence defenses and monitoring are in place, or the next evidence step is explicit.