---

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

Copy# Log usage when using this skill
./scripts/log-skill.sh "debug" "manual" "$$"

What do you want to do?

1. Reproduce an issue → workflows/reproduce-issue.md
2. Find Root Cause → workflows/root-cause-analysis.md
3. Create Bug Report → templates/bug-report.template.md
4. 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. Use skills/debug/ for guidance and scripts/repro/ for artifacts.