dotfiles/.config/opencode/skills/systematic-debugging/SKILL.md

name, description, permalink

name	description	permalink
systematic-debugging	Use when encountering bugs, test failures, or unexpected behavior before proposing fixes	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