| name | systematic-debugging |
| description | Use when encountering any bug, test failure, or unexpected behavior — find root cause before proposing any fix |
| compatibility | opencode |
| license | MIT |
Systematic Debugging
Overview
Random fixes waste time and mask underlying issues. Core principle: Find root cause before attempting any fix. Symptom fixes are failure.
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
When to Use
Use for ANY technical issue. Especially when under time pressure, when you've already tried multiple fixes, or when you don't fully understand the issue.
The Four Phases
Complete each phase before proceeding.
Phase 1: Root Cause Investigation
- Read the exact error, symptom, and reproduction steps
- Reproduce consistently
- Check recent diffs, dependencies, and config changes
- Trace the failing boundary and the data flow backward
Phase 2: Pattern Analysis
- Find a working comparison point
- Compare working versus broken behavior directly
- List the concrete differences
Phase 3: Hypothesis and Testing
- State one hypothesis
- Make the smallest possible test or observation to validate it
- If the hypothesis fails, discard it and form a new one
Phase 4: Fix and Verify
- Create the smallest failing reproduction you can
- Implement one fix for the root cause
- Verify the original symptom is gone and regressions are absent
- If multiple fix attempts fail, stop and question the architecture
Red Flags — Return to Phase 1
- "Quick fix for now"
- Adding multiple changes at once
- Proposing solutions before tracing data flow
- Each fix reveals a new problem elsewhere
- Skipping test creation
Stop Conditions
- If you cannot reproduce the issue, do not claim a fix
- If you are stacking multiple speculative changes, return to Phase 1
- If three fix attempts fail, stop and reassess the architecture with the user
Fallbacks
- If the environment does not let you run the failing path, gather the strongest available evidence and say what remains unverified
- If no automated test exists, create the smallest reproducible check you can
- For extended techniques and examples, read
skills/systematic-debugging/reference.md only when needed
Related Skills
- test-driven-development — for creating the failing test in Phase 4
- completing-work — verify fix worked before claiming success
