Deep root cause analysis - finds the actual cause, not just symptoms
Performs deep root cause analysis to identify the actual origin of issues from errors, stack traces, or symptoms.
/plugin marketplace add Wirasm/PRPs-agentic-eng/plugin install prp-core@prp-marketplace<issue|error|stacktrace> [--quick]Input: $ARGUMENTS
Find the actual root cause - the specific code, config, or logic that, if changed, would prevent this issue. Not symptoms. Not intermediate failures. The origin.
The Test: "If I changed THIS, would the issue be prevented?" If the answer is "maybe" or "partially", you haven't found the root cause yet. Keep digging.
| Type | Description | Action |
|---|---|---|
| Raw symptom | Vague description, error message, stack trace | INVESTIGATE - form hypotheses, test them |
| Pre-diagnosed | Already identifies location/problem | VALIDATE - confirm diagnosis, check for related issues |
--quick flag present → Surface scan (2-3 Whys, ~5 min)Restate the symptom in one sentence. What is actually failing?
PHASE_1_CHECKPOINT:
Based on the symptom, generate 2-4 hypotheses. For each:
| Hypothesis | What must be true | Evidence needed | Likelihood |
|---|---|---|---|
| {H1} | {conditions} | {proof needed} | HIGH/MED/LOW |
| {H2} | {conditions} | {proof needed} | HIGH/MED/LOW |
Start with the most probable hypothesis.
PHASE_2_CHECKPOINT:
Execute the 5 Whys protocol for your leading hypothesis:
WHY 1: Why does [symptom] occur?
→ Because [intermediate cause A]
→ Evidence: [code reference, log, or test that proves this]
WHY 2: Why does [intermediate cause A] happen?
→ Because [intermediate cause B]
→ Evidence: [proof]
WHY 3: Why does [intermediate cause B] happen?
→ Because [intermediate cause C]
→ Evidence: [proof]
WHY 4: Why does [intermediate cause C] happen?
→ Because [intermediate cause D]
→ Evidence: [proof]
WHY 5: Why does [intermediate cause D] happen?
→ Because [ROOT CAUSE]
→ Evidence: [exact file:line reference]
| Valid Evidence | Invalid Evidence |
|---|---|
file.ts:123 with actual code snippet | "likely includes...", "probably because..." |
| Command output you actually ran | Logical deduction without code proof |
| Test you executed that proves behavior | Explaining how technology works in general |
Rules:
For code issues:
For runtime issues:
For "it worked before" issues:
git log --oneline -20
git diff HEAD~10 [suspicious files]
PHASE_3_CHECKPOINT:
| Test | Question | Pass? |
|---|---|---|
| Causation | Does root cause logically lead to symptom through evidence chain? | Y/N |
| Necessity | If root cause didn't exist, would symptom still occur? | N required |
| Sufficiency | Is root cause alone enough, or are there co-factors? | Document if co-factors |
If any test fails → root cause is incomplete. Go deeper or broader.
git log --oneline -10 -- [affected files]
git blame [affected file] | grep -A2 -B2 [line number]
Document:
For deep mode, document why other hypotheses were rejected:
| Hypothesis | Why Ruled Out |
|---|---|
| {H2} | {evidence that disproved it} |
| {H3} | {evidence that disproved it} |
PHASE_4_CHECKPOINT:
mkdir -p .claude/PRPs/debug
Path: .claude/PRPs/debug/rca-{issue-slug}.md
# Root Cause Analysis
**Issue**: {One-line symptom description}
**Root Cause**: {One-line actual cause}
**Severity**: {Critical/High/Medium/Low}
**Confidence**: {High/Medium/Low}
---
## Evidence Chain
WHY: {Symptom occurs}
↓ BECAUSE: {First level cause}
Evidence: `file.ts:123` - {code snippet}
WHY: {First level cause}
↓ BECAUSE: {Second level cause}
Evidence: `file.ts:456` - {code snippet}
{...continue...}
↓ ROOT CAUSE: {The fixable thing}
Evidence: `source.ts:789` - {problematic code}
---
## Git History
- **Introduced**: {commit hash} - {message} - {date}
- **Author**: {who}
- **Recent changes**: {yes/no, when}
- **Type**: {regression / original bug / long-standing}
---
## Fix Specification
### What Needs to Change
{Which files, what logic, what the correct behavior should be}
### Implementation Guidance
```{language}
// Current (problematic):
{simplified example}
// Required (fixed):
{simplified example}
path/to/file.ts:LINE - {why}
**PHASE_5_CHECKPOINT:**
- [ ] Report created
- [ ] All sections filled
- [ ] Fix specification is actionable
---
## Phase 6: OUTPUT - Report to User
```markdown
## Root Cause Analysis Complete
**Issue**: {symptom}
**Root Cause**: {cause}
**Confidence**: {High/Medium/Low}
**Report**: `.claude/PRPs/debug/rca-{issue-slug}.md`
### Summary
{2-3 sentence explanation of what was found}
### The Fix
{1-2 sentence description of what needs to change}
### Next Steps
- Review the report for full evidence chain
- Implement the fix following the specification
- Run verification steps to confirm resolution
Symptoms lie. The error message tells you what failed, not why.
First explanation is often wrong. Resist the urge to stop early.
No evidence = no claim. "Likely", "probably", "may" are not allowed.
Test, don't just read. Execution proves behavior; reading proves intent.
Git history is mandatory. In deep mode, you must include when/who/why.
The fix should be obvious. If your root cause is correct, the fix writes itself.