name: systematic-debugging
description: Investigate bugs, test failures, and unexpected behavior through root-cause analysis before proposing fixes. Use when encountering any technical issue.
license: MIT
compatibility:
opencode: ">=0.1"
metadata:
category: debugging
phase: investigation
Skill: Systematic Debugging
This skill enforces root-cause investigation before any fix attempt. Random fixes waste time and create new bugs.
When to Use
Use for any technical issue:
- Test failures
- Bugs in production or development
- Unexpected behavior
- Performance problems
- Build failures
- Integration issues
Do not skip this skill when:
- The issue seems simple (simple bugs have root causes too)
- You are under time pressure (systematic debugging is faster than thrashing)
- A fix seems obvious (obvious fixes often mask the real problem)
Execution Model
- Primary agent runs this skill directly.
- Rationale: Debugging requires iterative investigation in the same context. Delegating to a subagent loses the accumulated understanding.
- Exception: For multi-component issues spanning independent subsystems, delegate per-subsystem investigation to separate agents via the
dispatch-parallel-agents skill.
Workflow
Phase 1: Root Cause Investigation
No fixes are allowed until this phase is complete.
- Read error messages carefully -- stack traces, line numbers, error codes. Do not skip past them.
- Reproduce consistently -- determine the exact steps. If not reproducible, gather more data instead of guessing.
- Check recent changes --
git diff, recent commits, new dependencies, config changes, environmental differences. - Gather evidence at component boundaries -- for multi-layer systems (CI -> build -> deploy, API -> service -> database), add diagnostic logging at each boundary to identify where the failure occurs.
- Trace data flow -- follow the bad value backward through the call stack to its origin. Fix at the source, not at the symptom.
Phase 2: Pattern Analysis
- Find working examples -- locate similar working code in the same codebase.
- Compare against references -- if implementing a pattern, read the reference implementation completely. Do not skim.
- Identify differences -- list every difference between working and broken code, however small.
- Understand dependencies -- what components, settings, config, and environment does this code need?
Phase 3: Hypothesis and Testing
- Form a single hypothesis -- state clearly: "I think X is the root cause because Y."
- Test minimally -- make the smallest possible change to test the hypothesis. One variable at a time.
- Verify before continuing -- if the hypothesis is wrong, form a new one. Do not stack fixes.
- Acknowledge unknowns -- if you do not understand something, say so. Do not pretend.
Phase 4: Implementation
- Fix the root cause, not the symptom.
- One change at a time -- no "while I'm here" improvements, no bundled refactoring.
- Verify the fix -- run the relevant tests, confirm the issue is resolved, confirm no regressions.
- If 3+ fixes have failed -- stop. The issue is likely architectural, not a bug. Discuss with the user before attempting more fixes.
Rules
- No fixes without investigation: Phase 1 must be complete before proposing any fix.
- One hypothesis at a time: Do not apply multiple changes simultaneously.
- Evidence over intuition: Every fix must be justified by evidence from the investigation, not by "it might work."
- Escalate after 3 failed attempts: Three failed fixes indicate an architectural problem. Stop fixing and discuss with the user.
- Do not increase timeouts as a fix: Find the real timing issue instead.
- Read error messages completely: Stack traces contain the answer more often than not.