debug-it

name	debug-it
description	Track down a bug methodically instead of guessing (use when the user reports something is broken / throwing / not working)
version	1.0.0
author	0pen-sourcer
tools	["run_command","read_file","grep_search","edit_file"]

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.