A systematic debugging skill for AI coding assistants. Stop the "fix-guess-fail-repeat" loop.
When debugging with AI assistants, you've probably experienced this:
- "Surface-level fixes" - AI spots something that looks wrong and immediately "fixes" it, without understanding the root cause
- "Confident hallucinations" - AI doesn't know the answer but won't admit it, generating plausible-sounding but wrong solutions
- "Outdated knowledge" - AI's training data is months or years old, leading to deprecated API calls and obsolete patterns
- "The endless loop" - Fix → New error → Fix → New error → ... until you both give up
This skill forces AI to diagnose before fixing, explicitly acknowledge uncertainty, and ask for help when needed.
This is a Claude Code Skill - a reusable prompt that activates when you invoke /debug. It transforms how Claude approaches debugging:
| Without Debug-First | With Debug-First |
|---|---|
| Sees error → Immediately modifies code | Sees error → Asks clarifying questions first |
| Assumes it knows the technology | Declares knowledge gaps about recent SDKs |
| Fixes symptoms | Locates root cause through binary search |
| Keeps trying when stuck | Triggers "direction check" after 2 failures |
| Never admits uncertainty | Explicitly states confidence levels |
# Navigate to your home directory's Claude skills
mkdir -p ~/.claude/skills
# Clone or download the skill
curl -o ~/.claude/skills/debug https://raw.githubusercontent.com/YUHAO-corn/debug-first-ai/main/skill/debug/SKILL.mdOr manually copy skill/debug/SKILL.md to ~/.claude/skills/debug.
# In your project root
mkdir -p .claude/skills/debug
cp /path/to/SKILL.md .claude/skills/debug/Once installed, simply type /debug in Claude Code when you encounter a bug:
> /debug
The login button doesn't work. It was working yesterday.
Claude will then:
- Assess information - Ask for error messages, expected vs actual behavior, reproduction steps
- Check knowledge gaps - Declare if it's unfamiliar with the specific technology/version
- Diagnose without modifying - Provide analysis with confidence levels
- Add verification logs - Suggest strategic console.log placements
- Fix only after confirmation - Modify code only after you confirm the diagnosis
Before any analysis, verify you have:
- Complete error message/stack trace
- Expected behavior vs actual behavior
- Where the problem occurs (input/processing/output)
- Relevant logs
- Reproduction steps: Is it consistent? What's the minimal repro?
Declare uncertainty for:
- SDKs/APIs released after training cutoff (2024+)
- Fast-iterating frameworks (AI SDK, Vercel AI, LLM APIs)
- Uncommon or internal libraries
Format: "This involves [technology]. My knowledge may be outdated. Please provide official docs or a working reference."
No code modifications in this step.
Output:
- Scope: User code or third-party library issue?
- Possible causes (ranked by likelihood with confidence %)
- Information gaps
- Knowledge gaps
- Verification plan (where to add logs)
After user confirms direction, add strategic logging.
Pre-requisites:
- Root cause confirmed via logs/evidence
- User approved the diagnosis
- Reference obtained for unfamiliar tech
Trigger: 2+ failed fixes, or new error types appearing
- Question the source: Is this my recommendation or from a reference?
- Request reference: Any open source implementations doing similar things?
- Challenge assumptions: Are we solving the right problem?
- Question the problem itself: Is this the real issue or a symptom?
AI's Hidden Failure Modes
The Dunning-Kruger AI: LLMs are trained to be helpful and confident. They don't naturally say "I don't know" - they generate the most statistically likely response, which might be plausible but wrong.
Pattern matching ≠ Understanding: AI recognizes patterns but doesn't truly "debug". It matches your error to similar patterns in training data, which fails for novel issues or recent framework changes.
No feedback loop: Unlike human developers who learn from production incidents, AI can't update its knowledge from your specific codebase or recent experiences.
- Forced introspection: Making AI explicitly state its confidence prevents overconfident guessing
- Binary search discipline: Localizing where the problem occurs prevents shotgun debugging
- Direction checks: Catching wrong-direction fixes early saves hours of wasted effort
- Knowledge boundaries: Knowing when AI is in unfamiliar territory lets you bring in the right resources
Without Debug-First:
User: The API returns 500 error
AI: Let me fix the error handling... [modifies code]
User: Still broken
AI: Let me try a different approach... [modifies more code]
[3 hours later, codebase is now a mess]
With Debug-First:
User: /debug The API returns 500 error
AI: I need more information:
- What endpoint?
- What's in the server logs?
- Did this work before? What changed?
User: [provides logs showing database connection timeout]
AI: Diagnosis (90% confidence):
Root cause: Database connection pool exhausted
Evidence: Timeout errors in logs, started after traffic spike
Before fixing, let's verify:
Add this log to check pool status: [...]
User: [confirms pool is exhausted]
AI: Now fixing with confirmed diagnosis: [targeted fix]
PRs welcome! Especially:
- Translations to other languages
- Adaptations for other AI assistants (Cursor, Copilot, etc.)
- Additional debugging scenarios and edge cases
MIT - Use freely, attribute if you share.
Born from countless debugging sessions where AI confidently broke things while trying to fix them. This skill encodes hard-won lessons about working with AI's limitations rather than against them.