37 lines
1.3 KiB
Markdown
37 lines
1.3 KiB
Markdown
---
|
|
name: systematic-debugging
|
|
description: Diagnose failures with a hypothesis-first workflow, evidence capture, and escalation rules aligned to planner/builder
|
|
permalink: opencode-config/skills/systematic-debugging/skill
|
|
---
|
|
|
|
# Systematic Debugging
|
|
|
|
Use this skill when tests fail, behavior regresses, or the root cause is unclear.
|
|
|
|
## Workflow
|
|
|
|
1. Define the failure precisely (expected vs actual, where observed, reproducible command).
|
|
2. Capture a baseline with the smallest reliable repro.
|
|
3. List 1-3 concrete hypotheses and rank by likelihood.
|
|
4. Test one hypothesis at a time with targeted evidence collection.
|
|
5. Isolate the minimal root cause before proposing fixes.
|
|
6. Verify the fix with focused checks, then relevant regression checks.
|
|
|
|
## Evidence Requirements
|
|
|
|
- Record failing and passing commands.
|
|
- Keep key logs/errors tied to each hypothesis.
|
|
- Note why rejected hypotheses were ruled out.
|
|
|
|
## Planner/Builder Alignment
|
|
|
|
- Planner: use findings to shape bounded implementation tasks and verification oracles.
|
|
- Builder: if contradictions or hidden dependencies emerge, escalate back to planner.
|
|
- After two failed verification attempts, stop, record root cause evidence, and escalate.
|
|
|
|
## Output
|
|
|
|
- Root cause statement.
|
|
- Fix strategy linked to evidence.
|
|
- Verification results proving the issue is resolved and not regressed.
|