---
title: root-cause-tracing
type: note
permalink: 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:

```ts
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.