tools-debugging-root-cause

Root Cause Tracing

Overview

Bugs often surface deep in a stack trace—far away from the code that actually caused them. This skill teaches you to walk the chain backward until you reach the true trigger, then reinforce defenses so the issue cannot recur.

Core principle: Never patch just the symptom. Follow the evidence upstream and fix the source.

When to Use

• Error occurs deep inside execution (nested call stack, worker, async task).
• Stack trace is long or unhelpful; unclear where invalid data originated.
• Behavior differs across tests/runs and you need to identify the polluting test.
• You suspect earlier code (setup, beforeEach, fixtures) seeded bad state.

Decision flow:

Bug surfaces deep? → yes → Can you trace back? → yes → Trace to original trigger → Add defense-in-depth → Done
                                          ↘ no → Temporary symptom fix (last resort)

Tracing Process

1. Observe the symptom
   • Capture the exact error message, location, and context (git init failed in ...).
2. Identify immediate cause
   • Locate the line/function performing the failing action (execFileAsync('git', ...)).
3. Ask who called it
   • Walk up the call graph (stack trace, search references). Document each hop.
4. Inspect parameters/state
   • Determine what inputs were passed (e.g., projectDir = '').
5. Continue upstream
   • Repeat until you find where the bad value originated (e.g., fixture accessed before setup ran).
6. Fix at the source
   • Correct the earliest point, then add guards down the stack to prevent reintroduction.

Instrumentation & Stack Traces

When static tracing stalls, instrument the suspicious operation before it runs:

async function gitInit(directory: string) {
  const stack = new Error().stack;
  console.error('DEBUG git init', {
    directory,
    cwd: process.cwd(),
    nodeEnv: process.env.NODE_ENV,
    stack,
  });

  await execFileAsync('git', ['init'], { cwd: directory });
}