debug
Systematic debugging with structured reproduction and root cause analysis.
When & Why to Use This Skill
This Claude skill provides a systematic framework for software debugging, focusing on structured reproduction and in-depth root cause analysis. It helps developers move beyond guesswork by implementing a 'verify-first' methodology, ensuring that every bug is consistently reproduced before a fix is applied, which significantly improves code reliability and troubleshooting efficiency.
Use Cases
- 1. Bug Reproduction: Creating isolated test cases or scripts to consistently trigger and verify reported issues before attempting a fix.
- 2. Root Cause Analysis: Systematically investigating software failures to identify the underlying logic errors or environmental factors.
- 3. Standardized Bug Reporting: Generating detailed, actionable bug reports using structured templates to improve team communication and resolution speed.
- 4. Error Message Interpretation: Researching and resolving cryptic error messages through common references and systematic analysis of failing logs.
| name | debug |
|---|---|
| description | Systematic debugging with structured reproduction and root cause analysis. |
| last_updated | 2025-12-20 |
Debug Skill
Overview
Don't guess; verify. This skill guides you through the systematic process of identifying, reproducing, and fixing bugs.
When To Use
- Users report a bug
- You encounter an unexpected error
- Tests are failing inexplicably
Instrumentation
# Log usage when using this skill
./scripts/log-skill.sh "debug" "manual" "$$"
What do you want to do?
- Reproduce an issue →
workflows/reproduce-issue.md - Find Root Cause →
workflows/root-cause-analysis.md - Create Bug Report →
templates/bug-report.template.md - Research Error Messages →
references/common-errors.md
The Golden Rule of Debugging
"If you haven't reproduced it, you haven't fixed it."
Always implement a reproduction case (test or script) BEFORE attempting a fix. Highly recommended to use the template at docs/templates/repro-script-template.sh and store artifacts in scripts/repro/.
[!NOTE] No top-level
debug/folder exists. Useskills/debug/for guidance andscripts/repro/for artifacts.