dotfiles/.config/opencode/skills/systematic-debugging/root-cause-tracing.md

title, type, permalink

title	type	permalink
root-cause-tracing	note	opencode-config/skills/systematic-debugging/root-cause-tracing

Root-Cause Tracing

Overview

Many bugs appear deep in a stack trace, but the origin is often earlier in the call chain.

Core principle: trace backward to the original trigger, then fix at the source.

When to Use

Use this when:

• The symptom appears far from where bad input was introduced
• The call chain spans multiple layers or components
• You can see failure but cannot yet explain origin

Tracing Process

1. Capture the symptom clearly

   • Exact error text, stack frame, and context.

2. Find immediate failure point

   • Identify the exact operation that throws or misbehaves.

3. Walk one frame up

   • Determine who called it and with which values.

4. Repeat until source

   • Continue tracing callers and values backward until you find where invalid state/data originated.

5. Fix at source

   • Correct the earliest trigger rather than patching downstream symptoms.

Instrumentation Tips

When manual tracing is hard, add targeted instrumentation before the risky operation:

const stack = new Error().stack;
console.error('debug context', {
  input,
  cwd: process.cwd(),
  envMode: process.env.NODE_ENV,
  stack,
});

Guidelines:

• Log before failure-prone operations, not after.
• Include values that influence behavior.
• Capture stack traces for call-path evidence.

Common Mistake

Mistake: fixing where the error appears because it is visible.

Better: trace backward and fix where incorrect state is first introduced.

Pair with Layered Defenses

After fixing the source, apply layered validation from defense-in-depth.md so similar failures are blocked earlier in the future.