systematic-debugging · Systematic Debugging
A general debugging-methodology skill with one iron law: find the root cause before proposing any fix — symptom fixes count as failure.
Its four phases must be completed in order: root-cause investigation (read errors, reproduce reliably, check recent changes, instrument component boundaries, trace data flow) → pattern analysis (find working references, list every difference) → single-hypothesis minimal testing → write a failing test, then fix the root cause. Fits test failures, production bugs, build failures, and performance issues alike.
Example invocation: "This test is failing — debug it by the book, don't touch the code yet."
Full brief
Positioning
systematic-debugging is a debugging-discipline skill for any bug, test failure, or unexpected behavior: it replaces guess-and-patch with a fixed four-phase process, avoiding the rework that thrashing always costs.
Core capabilities
- Root-cause investigation: read errors and stack traces fully; reproduce reliably; check recent changes (git diff, dependencies, environment drift); instrument component boundaries with logging in multi-component systems; trace bad values up deep call stacks.
- Pattern analysis: find similar working code in the same codebase; read reference implementations completely; list every difference; map dependencies and hidden assumptions.
- Hypothesis & testing: one hypothesis at a time, minimal-change tests, one variable at a time; say "I don't know", research, or ask for help instead of guessing.
- Root-cause fix: write the simplest failing test first (the test-driven-development skill fits here); one change at a time; verify the fix with no regressions; after 3 failed attempts, stop and question the architecture.
Workflow
The four phases must be completed in order — no skipping:
- Root-cause investigation: no fix may be proposed until this is done
- Pattern analysis: find the pattern before touching code
- Hypothesis & testing: scientific method, one hypothesis, one variable
- Implementation: fix the root cause, not the symptom; verify, then close
Inputs & outputs
| Input | Notes |
|---|---|
| Error message / stack trace | Required |
| Reproduction steps | Provide if possible |
| Relevant code locations | Optional |
Output: root-cause conclusion, failing test case, root-cause fix plan.
Boundaries with adjacent skills
- verification-before-completion: the gate before claiming completion (evidence before assertions).
- systematic-debugging (this): the investigation process when something is broken (root cause before fixes). The two pair well: this skill's fix phase explicitly requires verification-before-completion to confirm the fix works.
Fit
- Test failures, production bugs, build failures, performance issues, integration errors
- High-pressure "just fix it now" situations (the less time you have, the less you can skip)
- Cases where several fix attempts have already failed and a fresh angle is needed
Before you start
- No special setup; have the full error message and reproduction steps ready.
- The discipline holds especially under pressure — skipping the process guarantees rework.
systematic-debugging is part of the Aiglade Skill library. Invoke it from the Aiglade chat box in plain language.