root-cause-tracing_skill

Overview

This skill systematically traces bugs backward through the call stack to find the original trigger rather than treating symptoms. It guides you to identify the immediate failing operation, walk up callers, and discover the root cause so you can fix the source. The skill also recommends defensive layers and lightweight instrumentation to prevent regressions.

How this skill works

It inspects failure points (errors, unexpected filesystem or DB state) and asks "what called this?" to step up the call chain until the originating input or initialization is found. When manual tracing stalls, it adds targeted instrumentation (stack capture, pre-operation logs) and test bisection to pinpoint the polluter. Finally, it prescribes fixes at the origin plus validation layers to prevent recurrence.

When to use it

• An error appears deep inside a long call stack
• Stack trace shows many frames or points to unexpected cwd/file paths
• You see side effects in the repository or filesystem during tests
• You don’t know which test or initialization produced invalid input
• You want to harden code against future regressions

Best practices

• Start from the symptom and identify the immediate failing call before guessing fixes
• Ask who/what passed the suspicious value and trace one level up repeatedly
• Add pre-operation debug logs that include directory, cwd, env, and new Error().stack
• Use console.error in tests so output is visible; capture logs with redirected stderr
• Add validation at multiple layers instead of only fixing the symptom

Example use cases

• A test creates .git in the source tree—trace backward to find an empty cwd parameter and the test initialization bug
• Database opened with the wrong path—log call stacks to find where the path was built or passed
• Intermittent CI pollution—run a bisection script to find the first test that introduces the side effect
• Preventative hardening—add guards that refuse file operations outside temp directories in non-production envs
• Add stack-capture wrapper around risky operations (git init, file writes) to speed future debugging