| name | root-cause |
| description | Systematically analyze bugs, failures, or unexpected behavior to identify root causes. Examines code, data, dependencies, and logs without proposing fixes, producing a structured analysis that surfaces assumptions, evidence, gaps, and the simplest path forward. |
Root Cause Analysis Skill
Overview
Structured investigation workflow for understanding problems completely before proposing fixes. This skill produces a detailed analysis document that:
- Maps the problem systematically across code, data, and dependencies
- Identifies and challenges assumptions
- Documents evidence and gaps
- Ranks candidate root causes by probability
- Suggests the simplest possible solutions (without writing code)
Announce at start: "I'm using the root-cause-analysis skill to investigate this problem systematically."
Critical Rule: Do NOT write, edit, or suggest any code changes. This is a thinking-only skill that surfaces what to fix, not how to fix it.
When to Use This Skill
✅ Investigating unexpected behavior or errors in production or development
✅ Understanding why a test is failing repeatedly
✅ Diagnosing performance degradation or system failures
✅ Analyzing data corruption or inconsistent state
✅ Understanding third-party library issues or integration failures
✅ Tracing complex issues that span multiple services or layers
❌ Code review or style improvements (use relevant code standards)
❌ Feature development without a specific problem (use feature-writer)
Execution Steps
Step 1 — Gather the Problem Statement
Ask the user to describe:
- What is happening? The specific observed behavior or error
- When did it start? (If known: recent changes, deployment, environment shift)
- How often? (Always fails, intermittent, under specific conditions)
- What should happen? The expected behavior
- What environment? (Dev, staging, production; OS; version; config)
Synthesize into a one-sentence problem statement: name the behavior, context, and expected vs actual outcome.
State this back to the user for confirmation.
Step 2 — Read the Conversation
Review the entire conversation history for:
- Every symptom and error reported
- Stack traces or error messages
- Observed behaviors or data values
- Prior investigations or attempted fixes
- Context about when it started
- Any environment or config changes
Create a summary of what's been reported and flag anything unclear or contradictory.
Step 3 — Examine the Code
Read every relevant file, not just the ones mentioned:
- Follow the data flow upstream (what calls this code?) and downstream (what does it call?)
- Check for obvious issues: typos, wrong variables, stale logic, missing imports
- Look at recent changes (use
git log --oneline -20 and git diff for affected files)
- Identify all function/method signatures, parameters, and return types in the call path
- Check error handling and fallback paths
- Note any unusual patterns or assumptions embedded in the code
Document file paths and line numbers specifically — vague analysis is useless analysis.
Step 4 — Inspect the Data
Examine actual runtime values, not just the code:
- Request runtime data from the user: logs, database rows, config files, environment variables, API responses, event payloads
- If data is unavailable, say so explicitly — missing data is a finding, not a skip
- Trace the data through each transformation step
- Compare observed values against expected format/range/values
- Check for NULL values, type mismatches, encoding issues
- Look for off-by-one errors, precision loss, or unexpected mutations
For each data point, document:
- What the value is (literal observation, if available)
- Where it comes from (user input, DB, config, API, cache, etc.)
- What shape it's in (type, size, structure)
- Where it diverges from expectations (if at all)
- Availability (observed directly, inferred from code, or not available)
Step 5 — Map Dependencies
Identify every external and internal dependency involved:
- Third-party packages/crates (with versions)
- Workspace packages/crates
- System-level tools
- Services (APIs, databases, etc.)
- Environment (OS, runtime, platform)
Document each as a table:
| Dependency | Type | Version | Role in Problem | Status |
|---|
| name | package / crate / tool / service | version | what it does | OK / Suspect / Unverified |
Step 6 — Check Git History
For files involved in the problem:
- Run
git log --oneline -20 -- <filename> for recent changes
- For relevant commits, run
git show <sha> to examine what changed
- Look for logic changes, dependency updates, config changes, removed error handling
Step 7 — Check Logs
Request relevant logs from the user and examine for error messages, timeouts, and unexpected state transitions.
Step 8 — Check Prior Context
Ask:
- "Has this issue appeared before in a different form?"
- "Are there known issues or TODOs related to this area?"
- "Has this code been problematic in the past?"
Sections to Produce
1. Problem Statement
State the problem in one sentence — name the behavior, context, and expected vs actual outcome.
2. Assumptions
List every assumption with confidence level and basis.
3. Current Approaches
List every approach or fix that has been tried, with results.
4. Data State
Describe actual data at each stage of the problem.
5. Dependency Map
Table of all external and internal dependencies.
6. Supporting Evidence
List concrete evidence with interpretations and certainty levels.
7. Missing Information
List what you don't know but need to know, how to get it, and why it matters.
8. Root Cause Analysis
Rank candidate root causes by probability with key evidence.
9. Simplest Solutions
For each candidate root cause, describe the simplest possible fix.
Rules
- No code. Describe fixes in plain language only.
- Challenge every assumption. Verify things actually work.
- Follow the data. Trace actual runtime values — don't guess.
- Account for what you can't see. Missing data is a finding, not a skip.
- Check dependencies early. Version mismatches and missing features are common causes.
- Prefer the boring explanation. Check typos, wrong variables, stale caches first.
- Name specific files and lines. Vague analysis is useless analysis.
- If you're uncertain, say so. Scale confidence to evidence you actually have.
- After presenting the analysis, ask what to investigate next. Do NOT proceed to implementation.
Post-Analysis
After completing the analysis:
- Summarize findings — brief recap of the most likely root cause(s)
- Highlight critical gaps — what data or verification is most urgent
- Ask what's next — do NOT propose implementation
The user decides what to do with your analysis.
