Agent skill · software engineering · aiskillstore
systematic-debugging
Systematic methodology for debugging bugs, test failures, and unexpected behavior. Use when encountering any technical issue before proposing fixes. Covers root cause investigation, pattern analysis, hypothesis testing, and fix implementation. Use ESPECIALLY when under time pressure, "just one quick fix" seems obvious, or you've already tried multiple fixes. NOT for exploratory code reading.
Why this skill is useful
Provides a systematic methodology for debugging that includes specific investigative techniques and patterns not commonly known or documented.
What it needs
About 3k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
Systematic Debugging Random fixes waste time and create new bugs. Quick patches mask underlying issues. Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure. The Iron Law If you haven't completed Phase 1, you cannot propose fixes. --- The Four Phases Phase 1: Root Cause Investigation BEFORE attempting ANY fix: 1. Read Error Messages Carefully Don't skip past errors or warnings Read stack traces completely Note line numbers, file paths, error codes 2. Reproduce Consistently Can you trigger it reliably? What are the exact steps? If not reproducible, gather more data - don't guess 3. Check Recent Changes Git diff, recent commits New dependencies, config changes Environmental differences 4. Gather Evidence in Multi-Component Systems When system has multiple components (CI -> build -> signing, API -> service -> database): 5. Trace Data Flow See references/root-cause-tracing.md for backward tracing technique. Quick version: Where does bad value originate? Keep tracing up until you find the source. Fix at source, not symptom. Phase 2: Pattern Analysis 1. Find Working Examples - Locate similar working code in same codebase 2. Compare Against References - Read reference implementations COMPLETELY, don't skim 3. Identify Differences - List every difference between working and broken 4. Understand Dependencies - What settings, config, environment assumptions? Phase 3: Hypothesis and Testing 1. Form Single Hypothesis - "I think X is the root cause because Y" 2. Test Minimally - SMALLEST possible change, one variable at a time 3. Verify Before Continuing - Worked? Phase 4. Didn't? NEW hypothesis, don't stack fixes Phase 4: Implementation 1. Create Failing Test Case - Simplest reproduction, automated if possible 2. Implement Single Fix - ONE change, no "while I'm here" improvements 3. Verify Fix - Test passes? No regressions? 4. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/systematic-debugging