Agent skill · software engineering · aiskillstore
debugging
Four-phase debugging framework that ensures root cause identification before fixes. Use when encountering bugs, test failures, unexpected behavior, or when previous fix attempts failed. Enforces investigate-first discipline ('debug this', 'fix this error', 'test is failing', 'not working').
Why this skill is useful
Provides a structured four-phase debugging framework that helps identify root causes systematically, which the AI may not generate on its own.
What it needs
About 4k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
Systematic Debugger Find root cause before fixing. Symptom fixes are failure. Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST When to Use Answer IN ORDER. Stop at first match: 1. Bug, error, or test failure? → Use this skill 2. Unexpected behavior? → Use this skill 3. Previous fix didn't work? → Use this skill (especially important) 4. Performance problem? → Use this skill 5. None of above? → Skip this skill Use especially when: Under time pressure (emergencies make guessing tempting) "Quick fix" seems obvious (red flag) Already tried 1+ fixes that didn't work The Four Phases Complete each phase before proceeding. Phase 1: Root Cause Investigation BEFORE attempting ANY fix: 1. Read Error Messages Completely 2. Reproduce Consistently Can reproduce? Action --------------- ---------------------------------------------------- Yes, every time Proceed to step 3 Sometimes Gather more data - when does it happen vs not? Never Cannot debug what you cannot reproduce - gather logs 3. Check Recent Changes What changed that could cause this? Dependencies? Config? Environment? 4. Trace Data Flow (Root Cause Tracing) When error is deep in call stack: Technique: 1. Find where error occurs (symptom) 2. Ask: "What called this with bad data?" 3. Trace up until you find the SOURCE 4. Fix at source, not at symptom 5. Multi-Component Systems When system has multiple layers (API → service → database): Run once to find WHERE it breaks. Then investigate that layer. Phase 2: Pattern Analysis 1. Find Working Examples Locate similar working code in same codebase. What works that's similar? 2. Identify Differences Working code Broken code Could this matter? ---------------- -------------- ------------------ Uses async/await Uses callbacks Yes - timing Validates input No validation Yes - bad data List ALL differences. Don't assume "that can't matter." Phase 3: Hypothesis Testing 1. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/debugging--8d03a9