| name | debugging |
|---|---|
| version | 0.3.0 |
| description | Systematic debugging protocol for AI agents — how to diagnose, isolate, and fix bugs with discipline. |
| extends | Project Workflow Protocol |
This skill defines how to approach bugs systematically. No guessing. No random changes. Reproduce, isolate, fix, verify.
- Reproduce first. Never propose a fix for a bug you haven't seen. If you can't reproduce it, you don't understand it.
- Read the error. The full error message. The stack trace. The line number. Not just the first line.
- One change at a time. Change one thing, test, observe. Never change three things and hope one of them fixes it.
- The bug is in your code. Until proven otherwise, assume the framework, library, and runtime are correct. Your code is the most likely source.
- Get the exact steps that trigger the bug
- Reproduce it yourself (or see the error output)
- If you can't reproduce it: ask for more context, check environment differences
- Read the full error message and stack trace
- Identify the file and line where the error originates
- Trace the call chain — where was this function called from?
- Check if the error message tells you exactly what's wrong (it usually does)
Use binary search to narrow the problem:
Layer 1: Is it a UI issue or a data issue?
→ Check the data: is it correct at the source?
→ If data is correct, the bug is in rendering
→ If data is wrong, trace it backward
Layer 2: Is it a client issue or a server issue?
→ Check the network request/response
→ If response is wrong, debug the server
→ If response is correct, debug the client
Layer 3: Is it this commit or a previous one?
→ Use git log and git diff to find when it broke
→ git bisect for harder cases
- Don't just find what broke — understand why it broke
- Is this a one-off mistake or a systemic pattern?
- Are there other places in the codebase with the same issue?
- Fix the root cause, not just the symptom
- Make the smallest effective change
- If the fix is complex, write a plan before implementing
- Confirm the original bug is fixed
- Confirm no new bugs were introduced
- Run the full verification suite (tsc, build, tests)
- If the bug was in a critical path, add a regression test
- Write a clear commit message explaining what broke and why
- If the bug was subtle, add a code comment explaining the fix
- If the bug was a P0/P1, write a postmortem
| Category | Symptoms | Where to Look |
|---|---|---|
| Null/undefined | "Cannot read property of undefined" | Data flow — what's returning null? |
| Async timing | Intermittent failures, race conditions | Missing await, missing cleanup, stale closures |
| Type mismatch | Wrong data rendered, silent failures | API response shape vs. expected type |
| State management | UI out of sync, stale data | State updates, re-render triggers, cache invalidation |
| Environment | Works locally, fails in production | Environment variables, build config, API endpoints |
| Dependency | Broke after update | Check changelogs, run git diff package-lock.json |
| Anti-Pattern | Why It's Wrong | Do This Instead |
|---|---|---|
| "Try this and see if it works" | Guessing wastes time and erodes trust | Reproduce, isolate, understand, then fix |
| Changing multiple things at once | Can't tell which change fixed (or broke) it | One change at a time |
| Ignoring the error message | The answer is usually in the error | Read the full message and stack trace |
| Blaming the framework | 99% of the time, it's your code | Check your code first |
| Patch fixing without understanding | Creates new bugs and tech debt | Fix the root cause |
| Not adding a regression test | Same bug will return | Write a test that fails without the fix |
When presenting a bug fix to the user:
## Bug: {brief description}
**Symptom:** {what the user saw}
**Root Cause:** {what was actually wrong and why}
**Fix:** {what was changed — file:line references}
**Verification:** {how to confirm the fix works}
**Regression Risk:** {what else could be affected — "Low/Medium/High" with explanation}