# Root Cause Tracing

> Trace bugs backward to their origin, not just symptoms

- **Type:** Skill
- **Install:** `agentstack add skill-a-ariff-ariff-claude-plugins-root-cause-tracing`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [a-ariff](https://agentstack.voostack.com/s/a-ariff)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [a-ariff](https://github.com/a-ariff)
- **Source:** https://github.com/a-ariff/ariff-claude-plugins/tree/main/plugins/root-cause-tracing/skills/root-cause-tracing
- **Website:** https://github.com/a-ariff/ariff-claude-plugins#quick-start

## Install

```sh
agentstack add skill-a-ariff-ariff-claude-plugins-root-cause-tracing
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Root Cause Tracing

## Core Principle

```
TRACE BACKWARD TO THE BUG'S ORIGIN
Don't patch symptoms - fix the disease
```

## The Backward Trace Method

```
SYMPTOM
   ↓ Where does this value come from?
IMMEDIATE CAUSE
   ↓ What set that to wrong value?
DEEPER CAUSE
   ↓ Why did that happen?
ROOT CAUSE ← Fix HERE
```

## Practical Steps

### 1. Start at Symptom
```
Q: What exactly went wrong?
→ Document the exact symptom
→ Note file, line, error message
```

### 2. First Backward Step
```
Q: Where does this value/state come from?
→ Find the direct source
→ Check: is THIS the bug or just a carrier?
```

### 3. Keep Tracing
```
Q: What set THAT to the wrong value?
→ Follow the data flow backward
→ Each step: is this the origin or just passing it along?
```

### 4. Identify Root
```
SIGNS YOU'VE FOUND ROOT:
- Logic error in requirements interpretation
- Initial state incorrectly set
- Wrong assumption in algorithm
- Missing validation at entry point
- Broken invariant at creation
```

## Stop Conditions

**You've found root cause when:**
- There's no earlier source to trace
- The error was introduced HERE (not inherited)
- Fixing HERE prevents the bug entirely
- The "why" answer is: "wrong logic/design"

**You're still at symptoms if:**
- The wrong value came from somewhere else
- Another function passed bad data
- It's a consequence, not origin
- Fixing here = adding a workaround

## Common Patterns

| Bug Pattern | Root Usually At |
|-------------|-----------------|
| Wrong value displayed | Data calculation, not display code |
| Null pointer | Where object should've been created |
| Off-by-one | Loop bounds definition, not body |
| Race condition | Shared state design, not specific access |
| Invalid state | State transition logic, not current handler |

## Anti-Patterns (Don't Do This)

❌ **Symptom Patching**
```
// Bad: Fix where error happens
if (value === undefined) value = defaultValue
// Good: Find why value is undefined
```

❌ **Guard Stacking**
```
// Bad: Add guards everywhere
if (x) if (y) if (z) doThing()
// Good: Ensure x, y, z correct at source
```

❌ **Quick Fix Pressure**
```
"Just make it work" → Technical debt
Better: "5 more minutes tracing saves 5 hours debugging later"
```

## Verification

After identifying root cause:

1. **Explain the chain** - Symptom ← caused by ← caused by ← ROOT
2. **Confirm origin** - "This is where wrong value first appears"
3. **Fix at root** - Change the origin, not the symptoms
4. **Verify fix** - Original symptom gone + no new bugs

## Integration with Checkers

Use with:
- `assumption-checker` → Was root cause an assumption?
- `dependency-validator` → Was root cause a broken dependency?
- `pre-action-verifier` → Verify root cause fix before applying

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [a-ariff](https://github.com/a-ariff)
- **Source:** [a-ariff/ariff-claude-plugins](https://github.com/a-ariff/ariff-claude-plugins)
- **License:** MIT
- **Homepage:** https://github.com/a-ariff/ariff-claude-plugins#quick-start

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-a-ariff-ariff-claude-plugins-root-cause-tracing
- Seller: https://agentstack.voostack.com/s/a-ariff
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.