root-cause

---
name: root-cause
description: Find the root cause of a bug before proposing any fix. Use when tests fail, production misbehaves, a build breaks, or the user says stop guessing, debug this, or why is this happening.
---

# Root Cause

No fix before the cause is known. Symptom patches are failure.

Inspired by obra/superpowers systematic-debugging (MIT). Original Grok remake. No Superpowers cross-links.

## When to use
- Bug, test failure, unexpected behavior, perf cliff, build break
- Especially under time pressure or after a failed "quick fix"

## When NOT to use
- User asked for a design interview, not a debug
- The task is a greenfield feature with no failing behavior
- User already has a confirmed root cause and wants the patch only

## Inputs
- Symptom, error text, and how to reproduce if known
- Repo or logs if available

## Procedure

### Phase 1 - Investigate
1. Read the full error, stack, codes, paths. Do not skim.
2. Reproduce. If you cannot, gather data. Do not guess.
3. Check what changed: diffs, deps, config, environment.
4. In multi-layer systems, log what enters and leaves each boundary, then see where it breaks.
5. Trace bad values backward to the source. Fix there later, not at the symptom.

### Phase 2 - Pattern
- Find a working sibling in the same codebase.
- Read the reference all the way through.
- List every difference, even the boring ones.

### Phase 3 - Hypothesis
- Write one hypothesis: "X is the cause because Y."
- Change one variable to test it.
- If it fails, new hypothesis. Do not stack fixes.

### Phase 4 - Fix
- Smallest failing test first.
- One change. No drive-by refactors.
- Verify the test and the original symptom.
- After 3 failed fixes, stop and question the architecture with the user. Do not try a fourth guess.

## Output format
1. Evidence so far
2. Current phase
3. Single hypothesis or confirmed cause
4. Next smallest test
5. Only after confirmation: the fix

## Safety
- No exploit payloads. Defensive diagnosis only.
- Do not print secrets from logs. Redact tokens.
- Do not "just try" production writes to see what happens.

## Stop conditions
- Cause confirmed and fix verified
- Or 3 failed fixes and you asked to revisit architecture
- Or the issue is truly environmental and you documented what you checked