# root-cause-tracing

A skill that walks the agent backward through the call stack until it finds the original trigger, then fixes there instead of at the crash site.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1300 installs · ★ 1787
- Author: NeoLabHQ
- License: GPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/NeoLabHQ/context-engineering-kit/tree/HEAD/skills/root-cause-tracing/SKILL.md
- Updated: 2026-08-26
- HTML: https://affpapa.org/en/nevibecode/skills/root-cause-tracing

## What it does

The bug shows up deep in the stack: `git init` in the wrong directory, a file in the wrong place, a database opened with a bad path. The skill lays out the order of work. Observe the symptom, find the code that directly caused it, then ask what called that code. Keep going until you reach the value that started it all — an empty string, a stale variable.

When manual tracing stalls, the skill tells you to add instrumentation: `new Error().stack` before the risky operation, printed with `console.error()` because a logger may be suppressed in tests. Then run the suite with a grep on your debug tag and read the stacks for file names, line numbers, a repeated parameter. To find which test pollutes shared state, the kit ships `find-polluter.sh`, which runs tests one by one and stops at the first offender.

Fixing only where the error surfaced leaves the bug alive, because the same bad argument will arrive again. The skill pushes for a fix at the source plus validation at each layer — in the worked example that meant a getter that throws, a directory check, and a guard against `git init` outside a temp dir. The polluter script is bash, so on Windows it needs WSL.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add NeoLabHQ/context-engineering-kit --skill root-cause-tracing -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/root-cause-tracing/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/root-cause-tracing/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add NeoLabHQ/context-engineering-kit --skill root-cause-tracing -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/root-cause-tracing/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add NeoLabHQ/context-engineering-kit --skill root-cause-tracing -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/root-cause-tracing/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install NeoLabHQ/context-engineering-kit root-cause-tracing
```

2. **Manually: put the files in place**
- File: `.github/skills/root-cause-tracing/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add NeoLabHQ/context-engineering-kit --skill root-cause-tracing -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/NeoLabHQ/context-engineering-kit --path skills/root-cause-tracing
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/root-cause-tracing/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add NeoLabHQ/context-engineering-kit --skill root-cause-tracing -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/NeoLabHQ/context-engineering-kit/tree/HEAD/skills/root-cause-tracing/SKILL.md

## When to use it
- find where an empty or corrupted value entered a deep call
- read a long stack trace without patching the symptom
- identify the test that leaves junk in a shared directory
- add tracing before a risky operation when manual tracing dead-ends
- close the source of a bug with checks at several layers

## Example prompts
- This error surfaces deep in the stack — trace the call chain back to the original trigger and fix it there
- Add stack trace logging before git init and show me which test passes an empty projectDir
- Something creates .git in the source folder during tests — find the polluter with find-polluter.sh

## Similar
- [om-root-cause](https://affpapa.org/en/nevibecode/skills/om-root-cause.md) — skill · 2900 installs
- [principle-fix-root-causes](https://affpapa.org/en/nevibecode/skills/principle-fix-root-causes.md) — skill · 5700 installs
- [root-cause-analysis](https://affpapa.org/en/nevibecode/skills/root-cause-analysis.md) — skill · 884 installs
- [investigate-first](https://affpapa.org/en/nevibecode/skills/investigate-first.md) — skill · 105400 installs
- [debugging-wizard](https://affpapa.org/en/nevibecode/skills/debugging-wizard.md) — skill · 5100 installs
- [debugging-strategies](https://affpapa.org/en/nevibecode/skills/debugging-strategies.md) — skill · 13414 installs

## Other versions with the same name
- [root-cause-tracing · secondsky](https://affpapa.org/en/nevibecode/skills/secondsky-root-cause-tracing.md) — 426 installs

From the same set: [neolabhq/context-engineering-kit](https://affpapa.org/en/nevibecode/by/neolabhq/context-engineering-kit.md) — 64 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md