root-cause-tracing

Trace call stacks backward to identify the original bug trigger.

Updated Nov 3, 2025
One-click install
npx skills add https://github.com/ayourtch/kimichat --skill root-cause-tracing-ayourtch
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: root-cause-tracing
Source: https://github.com/ayourtch/kimichat/tree/main/skills/root-cause-tracing
Command: npx skills add https://github.com/ayourtch/kimichat --skill root-cause-tracing-ayourtch

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

This Skill prevents fixing symptoms by guiding a systematic backward trace through the call stack to identify the original trigger of invalid data or incorrect behavior.

Core Features & Use Cases

  • Backward Tracing Process: Guides step-by-step from symptom to immediate cause, up the call chain to the original trigger.
  • Instrumentation: Provides methods for adding stack traces and debug logging to capture context when manual tracing is difficult.
  • Polluter Identification: Includes a bisection script (find-polluter.sh) to pinpoint which test or code introduces unwanted state.
  • Use Case: When git init fails in an unexpected directory, use this skill to trace back through the cwd parameter's origin to find where an empty projectDir was passed.

Quick Start

I'm using the root-cause-tracing skill to find the source of the File not found error deep in the data-processor module.

Frequently Asked Questions about root-cause-tracing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I trace a bug back to its root cause through the call stack?

Root-cause tracing involves working backward from where an error occurs to identify the original trigger. Start at the symptom deep in execution, examine each function call up the chain, and locate where invalid data or incorrect behavior was first introduced—such as an empty parameter passed from an earlier function.

When should I use instrumentation and stack traces to debug instead of manual inspection?

Use instrumentation when errors occur deep in execution with long call chains that are difficult to trace manually. Stack traces and debug logging capture context automatically, making it practical to identify the root cause without stepping through every function call individually.

How do I find which test or code change introduced unwanted state?

Bisection scripts like `find-polluter.sh` pinpoint the specific test or code that introduces unwanted state. This isolates the source of a problem when multiple changes exist and symptoms appear after the state is already corrupted.

What's the difference between fixing a symptom and fixing the root cause?

Fixing a symptom patches the visible error without addressing its origin. Root-cause fixing traces the problem to its source—such as where an empty `projectDir` was first passed—and corrects it there, preventing the issue from recurring in other code paths.

Do I need stack traces to identify the root cause of every bug?

Not always. Simple bugs with short execution chains can be found through manual inspection. Stack traces and instrumentation become essential when errors occur deep in execution, multiple layers of abstraction exist, or the origin of invalid data is unclear.