Agent skill · software engineering · aiskillstore
systematic-debugging
Root cause analysis for debugging. Use when bugs, test failures, or unexpected behavior have non-obvious causes, or after multiple fix attempts have failed.
Why this skill is useful
Provides a systematic approach to debugging that includes specific diagnostic commands and evidence-gathering techniques not commonly known.
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 Core principle: Find root cause before attempting fixes. Symptom fixes are failure. Phase 1: Root Cause Investigation BEFORE attempting ANY fix: 1. Read Error Messages Carefully Read stack traces completely Note line numbers, file paths, error codes Don't skip warnings 2. Reproduce Consistently 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): Add diagnostic instrumentation before proposing fixes: Example: 5. Trace Data Flow See references/root-cause-tracing.md for backward tracing technique. Quick version: Where does bad value originate? Trace up call chain until you find the source. Fix at source. Phase 2: Pattern Analysis 1. Find Working Examples - Similar working code in codebase 2. Compare Against References - Read reference implementations COMPLETELY, don't skim 3. Identify Differences - List every difference, don't assume "that can't matter" 4. Understand Dependencies - Components, config, environment, assumptions Phase 3: Hypothesis and Testing 1. Form Single Hypothesis - "I think X is root cause because Y" - be specific 2. Test Minimally - SMALLEST possible change, one variable at a time 3. Verify - Worked → Phase 4. Didn't work → form NEW hypothesis, don't stack fixes 4. When You Don't Know - Say so. Don't pretend. Phase 4: Implementation 1. Create Failing Test Case Use the test-driven-development skill MUST have before fixing 2. Implement Single Fix ONE change at a time No "while I'm here" improvements 3. Verify Fix Test passes? Other tests still pass? Issue resolved? 4. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/systematic-debugging--60fecd