Root Cause Tracing

When bugs show up five calls deep in your stack and you're tempted to patch where the error appears, this walks you through tracing backward to find the actual source. The approach is straightforward: start at the symptom, follow the call chain up, and ask what values got passed at each level until you hit the original trigger. It includes practical debugging tactics like adding console.error stack traces before dangerous operations and running tests one by one to find polluters. The real example about git init running in the wrong directory because a test accessed an empty value too early shows exactly the kind of messy problem this solves. Solid for anyone who's tired of fixing symptoms instead of causes.

skills.sh installs: 438
GitHub stars: 248
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add secondsky/claude-skills --skill root-cause-tracing --agent claude-code

Installs into .claude/skills of the current project.

Files

Root Cause Tracing

Overview

Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.

Core principle: Trace backward through the call chain until you find the original trigger, then fix at the source.

When to Use

Use when:

Error happens deep in execution (not at entry point)
Stack trace shows long call chain
Unclear where invalid data originated
Need to find which test/code triggers the problem

The Tracing Process

1. Observe the Symptom

Error: git init failed in ~/project/packages/core

2. Find Immediate Cause

What code directly causes this?

await execFileAsync('git', ['init'], { cwd: projectDir });

3. Ask: What Called This?

WorktreeManager.createSessionWorktree(projectDir, sessionId)
  → called by Session.initializeWorkspace()
  → called by Session.create()
  → called by test at Project.create()

SKILL.md on GitHub