About debug-tools
An iterative debugging skill that guides investigation, evidence gathering, fixes, and verification. It tracks repeated failures and stops after three attempts to request an architectural assessment instead of continuing symptom-level fixes.
Key features
- 01Checklist-driven debugging workflow
- 02Ranks hypotheses using evidence
- 03Compares against working code
- 04Gathers runtime evidence with logs
- 05Verifies fixes and removes debug logs
- 06Escalates after three failed attempts
Use cases
- 01Investigate a reported bug
- 02Trace a regression against working code
- 03Add logs when runtime evidence is needed
- 04Clean up debug logs after verification
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/debug-toolsin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
README.mdagents/openai.yamlreferences/debugging-patterns.mdinvestigation.mdlog-cleanup.mdlog-injection.mdscripts/debug_logs.pyDetails
From the project READMEDebug Tools
Iterative debugging workflow that gates a fix on evidence and escalates after repeated failures.
Triggers
- Debug a bug ("debug this", "investigate", "trace issue", "fix bug", "why is X broken") → Step 1
- Regression or comparison ("used to work", "broke after the update", "works there but not here") → Step 2
- Add debug logs ("add debug logs", "inject logs", "trace with logs") → Step 3
- Cleanup logs ("remove debug logs", "cleanup logs") → Step 5
Workflow
Copy this checklist and tick it off:
Progress:
- [ ] Step 1: Investigate
- [ ] Step 2: Compare against working code (when needed)
- [ ] Step 3: Gather runtime evidence (when needed)
- [ ] Step 4: Fix and verify
- [ ] Step 5: Clean up logs
Start at the step the session's state calls for; a session already carrying evidence does not restart at Step 1.
Step 1. Investigate. Load investigation.md and work its sections from Understand the Bug through Rank Hypotheses. Done when every hypothesis carries a score and an evidence type, and the leading one either has evidence or names the runtime data it needs.
Step 2. Compare against working code. When analysis stalls and the broken code has to be diffed against a working example, or when the user reports that something used to work, load debugging-patterns.md. Done when the comparison or the regression trace is in hand; then return to Step 1 to re-rank.
Step 3. Gather runtime evidence. When reading the code cannot show the mechanism and only observing the running system can, load log-injection.md. Done when the reproduction's output is read; then return to Step 1 to re-rank.
Step 4. Fix and verify. Work the Propose Fix, Verify, and Report sections of investigation.md. Done when the reproduction no longer shows the symptom and the report is written. If the symptom remains, return to Step 1 with what the run showed.
Step 5. Clean up logs. Once the fix is verified, or on explicit request, load log-cleanup.md. Run it before changes go to version control. Done when the script's find reports no [DEBUG] statement and the project's syntax check passes.
A sensitive value never reaches an injected log — passwords, tokens, API keys, PII, session identifiers. This binds anywhere a log is added, including mid-investigation without Step 3 loaded.
Anti-Pattern: Symptom Whack-a-Mole
Fixing the same symptom in multiple places signals an architectural issue, not a localized bug. End each Step 4 report whose symptom remains with Attempt N of 3, and read that number back before proposing another fix. After three, stop fixing: the fourth move is an architectural assessment for the user — what was tried and why it failed, whether the issue is systemic (wrong abstraction, missing layer, flawed assumption), and the architectural change that would resolve it. Stop and reassess earlier when the root cause keeps changing, the changes grow with each attempt, or the confidence score drops between attempts.