# Debug It

> Track down a bug methodically instead of guessing (use when the user reports something is broken / throwing / not working)

- Skill: `0pen-sourcer/debug-it` (Agent Skill)
- Install (CLI): `npx skillmds@latest add 0pen-sourcer/debug-it`
- Raw SKILL.md: https://api.skillmd.com/api/skills/0pen-sourcer/debug-it/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 0pen-Sourcer (https://skillmd.com/u/0pen-sourcer)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/0pen-sourcer/debug-it

---


# Debug it, systematically

Find the ROOT cause before changing anything. Reproduce, isolate, fix, verify — no shotgun edits.

## Steps

1. **Reproduce.** Get the exact command or steps that trigger it. `run_command` to run it and capture the real error text / stack trace. If you cannot reproduce it, say so and ask for the exact steps — do not guess.
2. **Locate.** Read the top frame of the stack trace. `grep_search` for the error message or the failing function to find the code, then `read_file` around that line — enough context to understand it, not just the one line.
3. **Form ONE hypothesis** about the root cause and state it plainly. If you have two, test the more likely one first.
4. **Confirm before fixing.** Add a quick print/log or read the relevant state to prove the hypothesis is actually true. Do not fix a guess.
5. **Fix** the root cause with the smallest `edit_file` that addresses it — not a band-aid around the symptom.
6. **Verify.** Re-run the exact repro from step 1. Confirm the error is gone AND nothing adjacent broke (run the nearest tests if there are any).
7. Report: what was wrong, why, and the one-line fix.

## Don't

- Don't change code before you have reproduced the bug and confirmed the cause.
- Don't make several unrelated changes at once — one fix, then re-test.
- Don't silence the symptom (swallow the error, wrap it in a try/except that hides it) instead of fixing the cause.
- Don't leave the debug prints you added — clean them up before finishing.