root-cause-tracing · neolabhq — Claude Code skill: trace bugs to the source

What root-cause-tracing does

The bug shows up deep in the stack: git init in the wrong directory, a file in the wrong place, a database opened with a bad path. The skill lays out the order of work. Observe the symptom, find the code that directly caused it, then ask what called that code. Keep going until you reach the value that started it all — an empty string, a stale variable.

When manual tracing stalls, the skill tells you to add instrumentation: new Error().stack before the risky operation, printed with console.error() because a logger may be suppressed in tests. Then run the suite with a grep on your debug tag and read the stacks for file names, line numbers, a repeated parameter. To find which test pollutes shared state, the kit ships find-polluter.sh, which runs tests one by one and stops at the first offender.

Fixing only where the error surfaced leaves the bug alive, because the same bad argument will arrive again. The skill pushes for a fix at the source plus validation at each layer — in the worked example that meant a getter that throws, a directory check, and a guard against git init outside a temp dir. The polluter script is bash, so on Windows it needs WSL.