What problem does it solves?
This Skill prevents fixing symptoms by guiding a systematic backward trace through the call stack. It helps identify the original trigger of invalid data or incorrect behavior, ensuring fixes are applied at the source, not just where the error manifests.
Core Features & Use Cases
- Backward Tracing Process: Systematically traces errors up the call chain, from symptom to immediate cause to the original trigger, ensuring a thorough investigation.
- Instrumentation for Evidence: Provides guidance on adding diagnostic logging and stack traces to gather crucial context when manual tracing is difficult.
- Polluter Identification: Recommends a bisection script (
find-polluter.sh) to pinpoint which specific test or code introduces unwanted state or pollution during test runs.
- Use Case: When a
git init command fails in an unexpected directory, this skill helps you trace back through WorktreeManager, Session.create(), and test setup to find that an empty string was passed as projectDir at the very beginning, allowing you to fix the true source.
Quick Start
Example: Tracing an error deep in the stack
You: I'm using the root-cause-tracing skill to find the source of this error.
1. Observe the Symptom
Error: git init failed in /Users/jesse/project/packages/core
2. Find Immediate Cause
- Identify the code directly causing the error (e.g., execFileAsync('git', ['init'], { cwd: projectDir }))
3. Ask: What Called This?
- Trace up the call stack (e.g., WorktreeManager.createSessionWorktree -> Session.initializeWorkspace -> Session.create -> test)
4. Keep Tracing Up
- Identify the problematic value (e.g., projectDir = '' (empty string!))
5. Find Original Trigger
- Locate where the bad value originated (e.g., context.tempDir accessed before beforeEach)
Adding Stack Traces (if manual tracing is hard)
async function gitInit(directory: string) {
const stack = new Error().stack;
console.error('DEBUG git init:', { directory, cwd: process.cwd(), stack });
await execFileAsync('git', ['init'], { cwd: directory });
}
Finding Which Test Causes Pollution (using find-polluter.sh script)
./find-polluter.sh '.git' 'src/**/*.test.ts'
