root-cause-tracing
This skill teaches you to trace bugs backward through the call chain rather than fixing where errors appear. By working systematically up the stack—identifying what called each function and what values were passed—you locate the original trigger and fix the root cause. Includes instrumentation techniques, stack trace analysis, and real examples of finding pollution across test suites.
Root Cause Tracing helps you trace bugs backward through the call stack to find the original trigger instead of fixing symptoms.
AI-generated summary based on this skill's SKILL.md
Install
secondsky/claude-skills/root-cause-tracing · repository language: TypeScript
git clone https://github.com/secondsky/claude-skills
cp -r claude-skills/plugins/root-cause-tracing/skills/root-cause-tracing ~/.claude/skills/root-cause-tracingnpx skillfed install secondsky/claude-skills/root-cause-tracingFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I trace bugs backward through the call stack?
root-cause-tracing teaches you to work systematically upward from where an error appears, examining each function that called the one before it. Start by capturing the full stack trace, then follow the chain backward to identify what values were passed at each level and which function introduced the bad data. This backward tracing reveals the original trigger rather than just the symptom location.
What's the difference between finding root cause vs. fixing symptoms?
root-cause-tracing emphasizes identifying the original source of a bug rather than patching where it manifests. A symptom is where an error appears—often far down the call chain. The root cause is where invalid data originated or logic first went wrong. By tracing backward through the execution chain, you fix the actual problem once, preventing it everywhere, instead of applying band-aids at symptom sites.
How can root-cause-tracing help debug deep errors in code?
root-cause-tracing provides instrumentation and stack trace analysis techniques for errors buried in complex execution chains. Add logging at key points to capture function arguments and return values, then analyze the full trace to see where data became corrupted or logic failed. This systematic approach to analyzing the execution chain makes it possible to locate bug sources even in deeply nested or asynchronous code.
How do I find which test is causing pollution or side effects?
root-cause-tracing includes methods for tracing test pollution by instrumenting your test suite to track state changes and side effects. Capture stack traces when unexpected state modifications occur, then trace backward through the test execution chain to identify which test introduced the pollution. This reveals whether a test is leaking state, modifying shared resources, or leaving behind artifacts that affect other tests.
What instrumentation techniques does root-cause-tracing cover?
root-cause-tracing teaches you to add strategic logging and stack trace capture points throughout your code. Record function entry/exit, argument values, and return values at critical junctures. Use this instrumentation to build a complete picture of the execution chain, making it easier to spot where data went wrong or where control flow deviated from expectations.
SKILL.md
rendered from the published skill — quoted content, verbatim
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
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
plugins/root-cause-tracing/skills/root-cause-tracing/SKILL.md