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