| name | deep-debugging |
| description | Systematic, evidence-based debugging methodology. No guessing, no blind fixes — prove the cause first, then solve it. Use when: (1) a bug persists after the first fix attempt, (2) you're tempted to 'just try something', (3) you can't reproduce the issue consistently, (4) debugging auth/session/API issues, (5) the error message is vague or missing. Trigger phrases: 'debug', 'debugging', 'why doesn't X work', 'still broken', 'can't figure out', 'investigate this bug'. |
Deep Debugging
No blind fixes. No guessing. Prove the cause first, then solve it.
When you read this skill: STOP.
Set aside all fix ideas. You will change nothing until you know the root cause with 100% certainty.
PHASE 1 — Gather Evidence (observe only, touch nothing)
Answer these 4 questions with real evidence from logs/code:
1. What exactly happens?
- Exact error message or stack trace from logs
- HTTP status code (401? 403? 500? Redirect?)
- Which endpoint / function / service is affected
- What the user sees vs. what happens in the backend
2. When does it happen?
- Always or only sometimes?
- Only for specific users / roles / inputs?
- Since when — after which commit / change?
- Reproducible in which exact steps?
3. What should happen instead?
- Expected behavior in one clear sentence
- Actual behavior in one clear sentence
4. What was changed last?
- Last relevant commit
- New ENV variables, new dependencies, new migrations?
→ STOP. Only proceed to Phase 2 when all 4 questions are answered.
PHASE 2 — Form a Hypothesis (REQUIRED)
Write ONE concrete, testable hypothesis before touching anything:
"The bug occurs because [specific cause],
which I will prove/disprove by [concrete test]."
Good hypothesis:
"The user gets logged out because the JWT is not correctly set
in the cookie after login, which I'll prove by checking the
Set-Cookie header in the login response in backend logs."
Bad hypothesis:
"Something is wrong with the auth."
→ Too vague. Try again. Name the specific cause.
Report your hypothesis before continuing.
Format: 🔬 HYPOTHESIS: [your hypothesis]
PHASE 3 — Binary Search (narrow down the bug)
Split the problem in half. Test one half.
- Bug is there → split further
- Bug is not there → test the other half
For API / Backend bugs:
Request in → Middleware → Guard → Controller → Service → DB → Response
↑ ↑ ↑ ↑ ↑
Where does the chain break? Test each step individually.
For Auth / Session bugs:
Step 1: Login request → is JWT correctly generated?
Step 2: JWT in response → does it reach the client?
Step 3: Follow-up request → is JWT sent in the request?
Step 4: Guard/Middleware → is JWT correctly validated?
Step 5: Secret → is the same secret used for signing and verification?
For Frontend bugs:
User action → State update → API call → Process response → UI update
↑ ↑ ↑ ↑
Where does the chain break?
After each test step, report:
- ✅ [Step X] OK — bug is not here
- ❌ [Step X] BUG FOUND — [what exactly]
PHASE 4 — Fix (only now)
Only when the root cause is proven through Phases 1-3:
- Apply minimal fix — only what fixes the bug, nothing else
- Don't refactor while debugging — one problem, one fix
- Test immediately that the specific bug is gone
- Verify before reporting done
Common Error Patterns
| Symptom | Check First |
|---|
| User logged out after login | JWT secret mismatch, Cookie SameSite/Secure settings, CORS config |
| HTTP 401 on authenticated requests | JWT expired, wrong secret, missing Bearer token, validate() not called |
| HTTP 403 | Missing role, Guard logic, Tenant isolation blocking |
| HTTP 500 without stack trace | Unhandled Promise rejection, search console.error in logs |
| "Cannot read property of undefined" | Missing null checks, DB query returning null |
| Route not found (404) | Module not imported in AppModule, wrong controller prefix |
| DB error on startup | Migration not run, column doesn't exist, missing ENV variable |
| Cookie not set | SameSite=None + Secure=true needed for cross-origin |
| Cookie not sent | Cross-origin fetch needs credentials: 'include' |
Debug Commands
echo "$TOKEN" | cut -d. -f2 | base64 -d | jq .
curl -X POST http://localhost:4000/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"test@test.com","password":"test"}' \
-c /tmp/cookies.txt -v 2>&1 | grep "Set-Cookie"
curl http://localhost:4000/api/auth/me \
-b /tmp/cookies.txt -v 2>&1 | grep "HTTP"
lsof -i :PORT
git bisect start
git bisect bad
git bisect good abc1234
git bisect reset
For framework-specific debugging commands, see:
references/nestjs.md — NestJS + Next.jsreferences/patterns.md — Common bug patterns with real examples
Required Reporting Format
🔍 DEBUG REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Bug: [Exact error message from logs]
Located: [File:Line / Function / Service]
Root cause: [What actually happened — one clear explanation]
Evidence: [How the cause was proven]
Fix: [What was changed exactly — file + what]
Verified: [Yes — how tested, which test is green]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Escalation Protocol
If the bug still exists after 3 complete phase cycles:
- Document everything — write a full summary of what was tried and why it didn't work
- Escalate with context — don't just say "it's broken", say:
🚨 ESCALATION NEEDED
Bug: [description]
Tried: [3 hypotheses + what was proven/disproven]
Current state: [what we know for certain]
Help needed: [specific question or fresh eyes]
- Options:
- Ask a second developer / AI instance with full context
- Revert to last known working commit and debug the diff
- Add extensive logging and let it run in staging to gather more data
- Temporarily disable the feature and fix properly later
Rule: Never spend more than 3 cycles without escalating or reverting.
Absolute Rules
- NEVER fix without a hypothesis from Phase 2
- NEVER change multiple things at once
- NEVER "try something to see if it helps" — evidence-based fixes only
- NEVER skip a phase because the fix seems obvious
- After 3 fix attempts without resolution → escalate using the Escalation Protocol above
- Scope discipline: Fix only the reported bug, don't touch other issues
