Agent skill · software engineering · aiskillstore
systematic-debugging
Four-phase root cause investigation before attempting fixes. Use when debugging bugs, test failures, or unexpected behavior.
Why this skill is useful
Codifies a systematic debugging process that the AI could infer but now doesn't have to guess.
What it needs
About 2k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
Systematic Debugging ALWAYS find root cause before attempting fixes. Symptom fixes are failure. When to Use Encountering bugs or test failures Unexpected behavior in code Before proposing any fix The Four Phases Phase 1: Root Cause Investigation Before proposing any solution: 1. Read error messages thoroughly - Don't skip warnings or stack traces; they often contain exact solutions 2. Reproduce consistently - Verify you can trigger the issue reliably with documented steps 3. Check recent changes - Examine git diff, dependencies, and configuration modifications 4. Gather diagnostic evidence - In multi-component systems, add instrumentation at component boundaries 5. Trace data flow - Backward trace from the error to find where bad values originate Phase 2: Pattern Analysis Establish the pattern before fixing: 1. Locate similar working code in the codebase 2. Read reference implementations completely (not skimmed) 3. List every difference between working and broken code 4. Understand all dependencies and assumptions Phase 3: Hypothesis Testing Apply scientific method: 1. State your hypothesis clearly: "I believe X is failing because Y, evidenced by Z" 2. Test with the smallest possible change 3. Change only ONE variable at a time 4. Verify results before proceeding Phase 4: Implementation Fix the root cause systematically: 1. Create a failing test case first (TDD) 2. Implement a single fix addressing only the root cause 3. Verify the fix resolves the issue without breaking other tests 4. If fix doesn't work, return to Phase 1 Red Flags - STOP Immediately Proposing fixes without understanding the issue Attempting multiple simultaneous changes Assuming problems without verification Skipping evidence gathering Making "quick fixes" before investigation When 3+ Fixes Fail STOP. This signals an architectural problem, not a fixable bug: 1. Do not attempt another fix 2. Return to Phase 1 3. Question whether the underlying pattern/design is sound 4. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/systematic-debugging--ab176e