root-cause-tracing
Root Cause Tracing teaches you to follow bugs backward through the call chain rather than patching where errors appear. The skill walks through tracing methodology, stack instrumentation, and defense-in-depth validation to prevent recurrence.
Root Cause Tracing helps you systematically trace bugs backward through the call stack to find their original trigger instead of fixing symptoms.
AI-generated summary based on this skill's SKILL.md
Install
PracticalSwan/agent-skills/root-cause-tracing · repository language: Python
git clone https://github.com/PracticalSwan/agent-skills
cp -r agent-skills/root-cause-tracing ~/.claude/skills/root-cause-tracingnpx skillfed install PracticalSwan/agent-skills/root-cause-tracingFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I trace bugs backwards through the call stack?
Root Cause Tracing teaches you to follow the execution chain in reverse, starting from where an error appears and working backward to find its original trigger. Begin by capturing the full stack trace, then examine each frame to understand what state was passed down. Look for where assumptions broke or inputs diverged from expectations. This backward tracing reveals the true source rather than just the symptom location.
What's the difference between a symptom fix and a root cause fix?
Root Cause Tracing distinguishes between patching where an error surfaces versus fixing what caused it. A symptom fix stops the immediate failure but leaves the underlying problem to resurface elsewhere. A root cause fix addresses the original trigger—the point where invalid state, wrong assumptions, or unexpected inputs first entered the system. Symptom fixes are quick but brittle; root cause fixes are durable.
How can I find which test is causing the problem?
Root Cause Tracing includes techniques for identifying test pollution and tracing which test or code path is causing unexpected behavior. Add instrumentation to log state changes and execution order. Run tests in isolation versus together to narrow the culprit. Examine the call chain to see which test's side effects contaminated later ones. This systematic approach finds the polluter rather than just observing the failure.
Why add instrumentation and stack traces to debug issues?
Root Cause Tracing emphasizes that hard-to-find bugs often hide in complex execution paths where the symptom appears far from the source. Adding stack traces and instrumentation lets you map the full journey data took through your system. This visibility transforms guesswork into evidence, revealing exactly where assumptions failed and why the error occurred where it did.
What is defense-in-depth validation in Root Cause Tracing?
Root Cause Tracing teaches defense-in-depth validation to prevent bugs at multiple layers rather than relying on a single check. Validate inputs at entry points, intermediate transformations, and before use. Each layer catches different classes of problems and makes bugs easier to trace when they do slip through. This layered approach stops issues early and provides clearer signals about where things went wrong.
How does Root Cause Tracing help with systematic bug investigation?
Root Cause Tracing provides a methodology for systematic investigation: capture the full context, trace backward through the call chain, distinguish symptoms from sources, add instrumentation to fill gaps, and implement validation layers to prevent recurrence. This structured approach replaces random debugging with evidence-driven root cause analysis, turning hard-to-find bugs into solvable problems.
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
digraph when_to_use {
"Bug appears deep in stack?" [shape=diamond];
"Can trace backwards?" [shape=diamond];
"Fix at symptom point" [shape=box];
"Trace to original trigger" [shape=box];
"BETTER: Also add defense-in-depth" [shape=box];
"Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
"Can trace backwards?" -> "Trace to original trigger" [label="yes"];
"Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
"Trace to original trigger" -> "BETTER: Also add defense-in-depth";
}
Use when: - Error happens deep in
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 3 files
root-cause-tracing/CHANGELOG.md
root-cause-tracing/SKILL.md
root-cause-tracing/find-polluter.sh