feat: add verification and debugging workflow skills
This commit is contained in:
@@ -0,0 +1,66 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user