root-cause-tracing

What problem does it solve?

This Skill prevents fixing symptoms by guiding you to systematically trace bugs backward through the call stack, identifying the original trigger of invalid data or incorrect behavior, ensuring lasting solutions.

Core Features & Use Cases

• Backward Tracing Process: Guides from symptom to immediate cause, up the call chain to the original trigger, ensuring you find the true source of the problem.
• Instrumentation for Deep Errors: Provides patterns for adding stack traces and debug logging when manual tracing is difficult, capturing critical context.
• Polluter Bisection Script: Includes a script to automatically find which test creates unwanted files or state, streamlining the identification of polluting tests.
• Use Case: When an error occurs deep in a complex system (e.g., git init failing in the wrong directory), use this skill to pinpoint exactly where the bad value originated, ensuring you fix the source, not just the symptom.

Quick Start

1. Observe the Symptom

Error: git init failed in /Users/jesse/project/packages/core

2. Find Immediate Cause

What code directly causes this? (e.g., await execFileAsync('git', ['init'], { cwd: projectDir });)

3. Ask: What Called This?

Trace up the call stack (e.g., WorktreeManager.createSessionWorktree -> Session.initializeWorkspace -> test)

4. Find Original Trigger

Where did the bad value come from? (e.g., empty string passed as projectDir)

Use the find-polluter.sh script to identify polluting tests

./find-polluter.sh '.git' 'src/**/*.test.ts'