93 lines
2.8 KiB
Markdown
93 lines
2.8 KiB
Markdown
---
|
||
name: systematic-debugging
|
||
description: Use when encountering bugs, test failures, or unexpected behavior before proposing fixes
|
||
permalink: opencode-config/skills/systematic-debugging/skill
|
||
---
|
||
|
||
# Systematic Debugging
|
||
|
||
## Overview
|
||
|
||
Random fix attempts create churn and often introduce new issues.
|
||
|
||
**Core principle:** always identify root cause before attempting fixes.
|
||
|
||
## The Iron Law
|
||
|
||
```
|
||
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
|
||
```
|
||
|
||
If Phase 1 is incomplete, do not propose or implement fixes.
|
||
|
||
## When to Use
|
||
|
||
Use for any technical issue:
|
||
- Test failures
|
||
- Unexpected runtime behavior
|
||
- Build or CI failures
|
||
- Integration breakages
|
||
- Performance regressions
|
||
|
||
Use this especially when:
|
||
- You are under time pressure
|
||
- A "quick patch" seems obvious
|
||
- Previous fix attempts did not work
|
||
- You do not yet understand why the issue occurs
|
||
|
||
## Four-Phase Process
|
||
|
||
Complete each phase in order.
|
||
|
||
### Phase 1: Root-Cause Investigation
|
||
|
||
1. Read error messages and stack traces fully.
|
||
2. Reproduce the issue reliably with exact steps.
|
||
3. Check recent changes (code, config, dependency, environment).
|
||
4. Gather evidence at component boundaries (inputs, outputs, config propagation).
|
||
5. Trace data flow backward to the original trigger.
|
||
|
||
For deeper tracing techniques, see `root-cause-tracing.md`.
|
||
|
||
### Phase 2: Pattern Analysis
|
||
|
||
1. Find similar working code in the same repository.
|
||
2. Compare broken and working paths line by line.
|
||
3. List all differences, including small ones.
|
||
4. Identify required dependencies and assumptions.
|
||
|
||
### Phase 3: Hypothesis and Minimal Testing
|
||
|
||
1. State one concrete hypothesis: "X is failing because Y".
|
||
2. Make the smallest possible change to test only that hypothesis.
|
||
3. Verify result before making any additional changes.
|
||
4. If the test fails, form a new hypothesis from new evidence.
|
||
|
||
### Phase 4: Fix and Verify
|
||
|
||
1. Create a minimal failing reproduction (automated test when possible).
|
||
2. Implement one fix targeting the identified root cause.
|
||
3. Verify the issue is resolved and no regressions were introduced.
|
||
4. If fix attempts keep failing, stop and reassess design assumptions.
|
||
|
||
## Red Flags (Stop and Restart at Phase 1)
|
||
|
||
- "Let me try this quick fix first"
|
||
- "I’ll batch several changes and see what works"
|
||
- "It probably is X"
|
||
- Proposing solutions before tracing the data flow
|
||
- Continuing repeated fix attempts without new evidence
|
||
|
||
## Supporting Techniques
|
||
|
||
Use these companion references while executing this process:
|
||
|
||
- `root-cause-tracing.md` — trace failures backward through the call chain
|
||
- `condition-based-waiting.md` — replace arbitrary sleeps with condition polling
|
||
- `defense-in-depth.md` — add layered validation so recurrence is harder
|
||
|
||
## Related Skills
|
||
|
||
- `test-driven-development` — build minimal failing tests and iterate safely
|
||
- `verification-before-completion` — confirm behavior end-to-end before claiming done
|