tomevault-io Debugging
Announce at start: "Following the debugging skill to find root cause before fixing."
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you have not completed steps 1-4 below, you cannot propose fixes. Symptom fixes are failure.
Process
1. Observe
Collect the full picture before forming any hypothesis.
- Full stack trace and error message
- Application logs around the failure
- Environment details (OS, runtime, versions)
- Input data that triggered the failure
2. Reproduce
Create a minimal environment where the bug consistently occurs.
- Write a failing test that demonstrates the bug
- If untestable, document exact reproduction steps
- Confirm the test fails for the right reason
3. Isolate
Narrow down to the exact component or function.
- Binary search: disable half the code path, check if bug persists
- Check recent changes (
git log,git bisect) - Trace execution flow leading to the error
4. Diagnose
Identify the root cause — not just the symptom.
- Ask: "Why does this happen?" at least 3 times (5 Whys)
- List 3 potential causes before investigating any single one
- Check for edge cases: null, empty, boundary values, race conditions
5. Fix
Implement the minimal correction needed.
- Change only what is required to fix the root cause
- Do not refactor while debugging
- Do not fix unrelated issues in the same change
6. Verify
Confirm the fix is correct and complete.
- Reproduction test now passes
- Full test suite passes (no regressions)
- You can explain why the fix works
- Manual verification if applicable
Red Flags — STOP
| Signal | Action |
|---|---|
| Tempted to "just try something" | Go back to step 1 |
| Fix didn't work | You don't have root cause — go back to step 4 |
| Multiple fixes attempted | You're guessing — go back to step 3 |
| Under time pressure | Slow down — systematic is faster than thrashing |
| Issue seems simple | Simple bugs have root causes too — follow the process |
Related Skills
| When | Invoke |
|---|---|
| Bug fix requires multi-file changes | refactoring |
| Need to write regression test | testing |
| Fix touches security-sensitive code | secure-coding |
| Ready to submit the fix | pr-writing |
Deep Reference
For principles, rationale, anti-patterns, and examples:
guides/debugging-with-ai/debugging-with-ai.md
Converted and distributed by TomeVault — claim your Tome and manage your conversions.