trace

Root cause analysis for complex bugs. Use when initial fix fails or incident is severe. Traces Effect → Cause → Root with confidence levels and prevention hierarchy.

⭐23stars🔀0forks📁View on GitHub🕐Updated Jan 6, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill automates comprehensive root cause analysis (RCA) for complex software bugs and critical production incidents. By employing a structured 'Five Whys' methodology with confidence scoring, it helps engineering teams move beyond surface-level fixes to identify systemic technical and organizational gaps, ultimately generating a multi-tiered prevention strategy to improve long-term system reliability and minimize downtime.

Use Cases

  • Post-incident retrospectives: Automatically generating structured post-mortems for SEV 1-2 incidents, including detailed timelines and quantified business impact.
  • Persistent bug resolution: Investigating complex, multi-source failures where initial patches have failed to stop the issue from recurring in production.
  • Systemic gap identification: Analyzing contributing factors such as monitoring deficiencies, configuration drift, or process bottlenecks to strengthen SRE and DevOps practices.
  • Blameless culture implementation: Facilitating objective analysis of system failures that focuses on architectural and process improvements rather than individual human error.
nametrace
descriptionRoot cause analysis for complex bugs. Use when initial fix fails or incident is severe. Traces Effect → Cause → Root with confidence levels and prevention hierarchy.

trace

Root cause analysis when surface fixes fail.

When to Use

Trigger Action
Bug persists after initial fix Run trace
Production incident (SEV 1-2) Run trace
Complex failure (multiple sources) Run trace
Trivial bug (< 10 min fix) Skip

1. Timeline

HH:MM - [Event] - [System state] - [Action taken]

Note: detection time vs. start time (how long hidden?)

2. Five Whys

Effect: [What users/systems experienced]

Why 1: [Immediate cause] (X-Y% confident)
Why 2: [Underlying mechanism] (X-Y% confident)
Why 3: [System/process gap] (X-Y% confident)
Why 4: [Organizational factor] (X-Y% confident)
Why 5: [Root cause] (X-Y% confident)

Gates: < 70% any level → request logs/reproduction Root cause = deepest answer with ≥70% confidence

3. Contributing Factors

Beyond root cause, what amplified impact?

Process: Monitoring gaps, testing gaps, review gaps People: Unclear ownership, missing runbooks Technical: Dependency failures, capacity limits, config drift Context: Traffic patterns, deployment timing, external factors

List 2-4 factors with specific mechanisms.

Tools: Ishikawa for categorization, Iceberg for deep structure analysis.

4. Impact

Users: Count, experience, business cost (quantified) Systems: Downstream effects, data integrity, security

5. Prevention Hierarchy

Immediate (< 1 week)

1. [Code/config change]
   File: [path:line]
   Verification: [how to confirm]
   Owner: [who]

Short-Term (< 1 month)

1. [Alert/test/automation]
   Trigger: [when it fires]
   Owner: [who]

Long-Term (< 1 quarter)

1. [Architectural change]
   Problem class: [what it prevents]
   Effort: [story points]
   Owner: [who]

Each tier needs ≥1 item.

6. Blameless

See soul/references/blameless.md

Focus on system gaps, not individual mistakes.

Output

# Incident: [Title]

## Timeline
[Detection → Resolution]

## Five Whys
[With confidence per level]

## Contributing Factors
[2-4 items]

## Impact
[Quantified]

## Prevention
[Immediate / Short-Term / Long-Term]

## Top 3 Actions
1. [Task] | Owner: [Name] | Due: [Date]
2. ...
3. ...

Anti-Patterns

Bad Good
"Human error" Identify automation gap
"Communication failure" Identify process gap
"Be more careful" Add system safeguard
"Performance issue" Specific: "Pool exhausted at 1K req/s"