Debugging Skill
This skill defines how to approach bugs systematically. No guessing. No random changes. Reproduce, isolate, fix, verify.
Debugging Mindset
- 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.
Debugging Protocol
Step 1: Reproduce
- 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
Step 2: Read the Error
- 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)
Step 3: Isolate
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
Step 4: Understand the Root Cause
- 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?
Step 5: Fix
- Fix the root cause, not just the symptom
- Make the smallest effective change
- If the fix is complex, write a plan before implementing
Step 6: Verify
- 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
Step 7: Document
- 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
Common Bug Categories
| 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-Patterns
| 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 |
Reporting Format
When presenting a bug fix:
## 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}
1---2name: pwp-debug3description: Systematic debugging protocol — diagnose, isolate, and fix bugs with discipline. Use this skill whenever the user reports a bug, error, crash, or unexpected behavior. Also use when they say things like 'this is broken', 'not working', 'something's wrong', 'fix this', 'why is this failing', or share an error message or stack trace. Covers reproduce → isolate → root cause → fix → verify workflow.4---56# Debugging Skill78This skill defines how to approach bugs systematically. No guessing. No random changes. Reproduce, isolate, fix, verify.910## Debugging Mindset1112- **Reproduce first.** Never propose a fix for a bug you haven't seen. If you can't reproduce it, you don't understand it.13- **Read the error.** The full error message. The stack trace. The line number. Not just the first line.14- **One change at a time.** Change one thing, test, observe. Never change three things and hope one of them fixes it.15- **The bug is in your code.** Until proven otherwise, assume the framework, library, and runtime are correct. Your code is the most likely source.1617## Debugging Protocol1819### Step 1: Reproduce20- Get the exact steps that trigger the bug21- Reproduce it yourself (or see the error output)22- If you can't reproduce it: ask for more context, check environment differences2324### Step 2: Read the Error25- Read the **full** error message and stack trace26- Identify the **file and line** where the error originates27- Trace the **call chain** — where was this function called from?28- Check if the error message tells you exactly what's wrong (it usually does)2930### Step 3: Isolate31Use binary search to narrow the problem:3233```34Layer 1: Is it a UI issue or a data issue?35 → Check the data: is it correct at the source?36 → If data is correct, the bug is in rendering37 → If data is wrong, trace it backward3839Layer 2: Is it a client issue or a server issue?40 → Check the network request/response41 → If response is wrong, debug the server42 → If response is correct, debug the client4344Layer 3: Is it this commit or a previous one?45 → Use git log and git diff to find when it broke46 → git bisect for harder cases47```4849### Step 4: Understand the Root Cause50- Don't just find *what* broke — understand *why* it broke51- Is this a one-off mistake or a systemic pattern?52- Are there other places in the codebase with the same issue?5354### Step 5: Fix55- Fix the **root cause**, not just the symptom56- Make the **smallest effective change**57- If the fix is complex, write a plan before implementing5859### Step 6: Verify60- Confirm the original bug is fixed61- Confirm no new bugs were introduced62- Run the full verification suite (tsc, build, tests)63- If the bug was in a critical path, add a regression test6465### Step 7: Document66- Write a clear commit message explaining what broke and why67- If the bug was subtle, add a code comment explaining the fix68- If the bug was a P0/P1, write a postmortem6970## Common Bug Categories7172| Category | Symptoms | Where to Look |73|----------|----------|--------------|74| **Null/undefined** | "Cannot read property of undefined" | Data flow — what's returning null? |75| **Async timing** | Intermittent failures, race conditions | Missing await, missing cleanup, stale closures |76| **Type mismatch** | Wrong data rendered, silent failures | API response shape vs. expected type |77| **State management** | UI out of sync, stale data | State updates, re-render triggers, cache invalidation |78| **Environment** | Works locally, fails in production | Environment variables, build config, API endpoints |79| **Dependency** | Broke after update | Check changelogs, run `git diff package-lock.json` |8081## Anti-Patterns8283| Anti-Pattern | Why It's Wrong | Do This Instead |84|-------------|---------------|----------------|85| "Try this and see if it works" | Guessing wastes time and erodes trust | Reproduce, isolate, understand, then fix |86| Changing multiple things at once | Can't tell which change fixed (or broke) it | One change at a time |87| Ignoring the error message | The answer is usually in the error | Read the full message and stack trace |88| Blaming the framework | 99% of the time, it's your code | Check your code first |89| Patch fixing without understanding | Creates new bugs and tech debt | Fix the root cause |90| Not adding a regression test | Same bug will return | Write a test that fails without the fix |9192## Reporting Format9394When presenting a bug fix:9596```97## Bug: {brief description}9899**Symptom:** {what the user saw}100**Root Cause:** {what was actually wrong and why}101**Fix:** {what was changed — file:line references}102**Verification:** {how to confirm the fix works}103**Regression Risk:** {what else could be affected — "Low/Medium/High" with explanation}104```
shandar