debugging
Structured debugging workflow: reproduce, isolate, trace, fix, verify. Use when investigating bugs, unexpected behavior, or test failures. Guides systematic root-cause analysis instead of trial-and-error.
Best use case
debugging is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Structured debugging workflow: reproduce, isolate, trace, fix, verify. Use when investigating bugs, unexpected behavior, or test failures. Guides systematic root-cause analysis instead of trial-and-error.
Teams using debugging should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/debugging/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How debugging Compares
| Feature / Agent | debugging | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Structured debugging workflow: reproduce, isolate, trace, fix, verify. Use when investigating bugs, unexpected behavior, or test failures. Guides systematic root-cause analysis instead of trial-and-error.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Debugging Skill ## When to use this Skill Use this Skill when you are: - Investigating a bug report or unexpected behavior - Diagnosing a failing test - Tracking down a performance regression - Understanding why code behaves differently than expected ## The Debugging Workflow ### 1. Reproduce - Confirm the bug exists by reproducing the exact reported behavior - Identify the minimal steps or input to trigger the issue - Note the actual behavior vs. expected behavior - If the bug cannot be reproduced, gather more context before proceeding ### 2. Isolate - Narrow down where the bug occurs: - Which file, function, or module? - Which input conditions trigger it? - Does it happen consistently or intermittently? - Use binary search on recent changes if the bug is a regression - Remove variables: disable plugins, simplify input, use minimal config ### 3. Trace - Follow the execution path from input to the point of failure - Read error messages and stack traces carefully — they often point directly to the cause - Add targeted logging or debugging output at key decision points - Check assumptions: are variables the expected type and value at each step? - Look for common root causes: - Off-by-one errors - Null/undefined references - Race conditions or timing issues - Incorrect type coercion - Stale cache or state ### 4. Fix - Fix the root cause, not just the symptom - Make the smallest change that resolves the issue - Consider edge cases that may have the same root cause - Do not refactor surrounding code as part of the fix ### 5. Verify - Confirm the fix resolves the original reported behavior - Run the full test suite to check for regressions - If a test did not exist for this bug, add one - Test edge cases related to the fix ## Things to Avoid - Changing code randomly hoping something works (shotgun debugging) - Fixing symptoms instead of root causes - Making multiple changes at once — isolate each change - Ignoring intermittent failures — they are real bugs - Removing error handling to "fix" errors
Related Skills
qa-run
Run QA test suites against the local dev stack using Chrome DevTools and Playwright MCPs. Verifies environment, executes test flows, monitors for network errors, writes results, and creates Linear tickets for failures.
deploy-watch
Monitor GitHub Actions deploy workflows after merging a PR to staging. Polls until all deploys complete, diagnoses failures, and reports results.
tdd
Red-Green-Refactor test-driven development workflow. Guides the agent through writing failing tests first, then implementing code to pass them, then refactoring while keeping tests green.
linear-audit
Route audit findings to Linear as issues. Reads the most recent audit report from docs/audits/, parses findings at warning severity or above, and creates Linear issues in the project's configured team. Requires Linear MCP server to be available.
document-writer
Document generation skill for creating DOCX, PDF, PPTX, and other formatted documents. Guides structured content creation with proper formatting, headings, tables, and professional presentation.
code-reviewer
PR review, quality audit, and security checks. Invoke when reviewing code changes before merging or pushing. Performs structured review covering correctness, security, performance, and maintainability.
catholic
Apply reverent, faith-inspired Christian verbiage to non-code artifacts. Invoke when generating specs, plans, task lists, READMEs, or other documentation to infuse them with blessings, gratitude, and references to divine guidance. Never applies to source code or config files.
console-debugging
Use when debugging JavaScript errors, checking console warnings, analyzing browser logs, finding runtime errors, investigating console output, or troubleshooting browser issues. Provides console message analysis.
systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior. 4-phase root cause investigation — NO fixes without understanding the problem first.
systematic-debugging
Use when a bug is non-obvious or has resisted quick fixes — applies a 4-phase root cause analysis to find and permanently resolve the issue rather than patching symptoms
cpp-debugging
Use when a C++ failure involves memory lifetime, undefined behavior, native crashes, or debugger-only state — debug with symbols, sanitizers, and platform-native debuggers before patching symptoms
actions-debugging
Use when a GitHub Actions workflow fails — diagnose the run log, identify the root cause, and apply a targeted fix