67 lines
1.7 KiB
Markdown
67 lines
1.7 KiB
Markdown
---
|
|
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.
|