# Debug

> Troubleshoot and debug issues. Use when the user reports an error, a test failure, unexpected behavior, or asks to investigate why something isn't working.

- Skill: `seifbenayed/debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add seifbenayed/debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/seifbenayed/debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: SeifBenayed (https://skillmd.com/u/seifbenayed)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/seifbenayed/debug

---


# Debug

Help diagnose and troubleshoot the described issue or the most recent error.

## Steps

1. **Understand the problem**
   - Read any error messages or stack traces mentioned
   - Ask clarifying questions if the problem description is vague
   - Check recent git changes that might have caused the issue: `git diff HEAD~3`

2. **Reproduce**
   - If there's a failing test, run it to see the exact error
   - If it's a runtime issue, try to reproduce with minimal steps

3. **Investigate**
   - Find the relevant source files using the stack trace or error message
   - Trace the code path that leads to the error
   - Check for common issues:
     - Typos in variable or function names
     - Wrong types or missing type conversions
     - Missing imports or dependencies
     - Race conditions or async issues
     - Environment differences (missing env vars, wrong paths)
     - Recent changes that broke assumptions

4. **Form a hypothesis and verify**
   - State what you think the root cause is
   - Find evidence in the code that supports or refutes it
   - If needed, add targeted logging to narrow down the issue

5. **Report findings**
   - Root cause explanation (why it broke, not just what broke)
   - Suggested fix with specific code changes
   - How to prevent similar issues in the future

Do NOT make changes unless explicitly asked — diagnose and explain first. The user should decide whether and how to fix it.

$ARGUMENTS