root-cause-tracing

Root-cause tracing guides you backward through the call stack from the failure site to its original trigger. Start by observing the symptom, identify the immediate cause, then systematically trace through layers of code and data flow to find where the invalid data or behavior originated, using instrumentation like stack traces and diagnostic logging when needed.

Fixing symptoms—where errors appear—leads to recurring issues and wasted effort. Root-cause tracing finds the original trigger, enabling a permanent fix. This approach prevents the same bug from resurfacing in different contexts and reduces debugging cycles across your codebase.

Add instrumentation when stack traces are long, error origins are unclear, or you need to validate data flow across multiple layers. Diagnostic logging pinpoints where invalid data enters the system or where behavior deviates, bridging gaps the call stack alone cannot reveal.

Root-cause tracing includes the find-polluter.sh script, which bisects your test suite to identify which test generates unwanted side effects or state pollution, isolating the source of test failures and environmental contamination.

Yes. Root-cause tracing integrates with git for version tracking, npm for dependency and script management, and grep for searching code patterns and logs during systematic backward tracing through your call stack.

Once you locate the root cause, the skill guides a controlled return to systematic debugging Phase 2, where you apply the permanent fix, validate it across layers, and prevent recurrence by addressing the original trigger rather than its downstream symptoms.