tomevault-io Debug Pro
Systematic debugging methodology and language-specific debugging commands.
The 7-Step Debugging Protocol
- Reproduce — Get it to fail consistently. Document exact steps, inputs, and environment.
- Isolate — Narrow scope. Comment out code, use binary search, check recent commits with
git bisect. - Hypothesize — Form a specific, testable theory about the root cause.
- Instrument — Add targeted logging, breakpoints, or assertions.
- Verify — Confirm root cause. If hypothesis was wrong, return to step 3.
- Fix — Apply the minimal correct fix. Resist the urge to refactor while debugging.
- Regression Test — Write a test that catches this bug. Verify it passes.
Language-Specific Debugging
JavaScript / TypeScript
# Node.js debugger
node --inspect-brk app.js
# Chrome DevTools: chrome://inspect
# Console debugging
console.log(JSON.stringify(obj, null, 2))
console.trace('Call stack here')
console.time('perf'); /* code */ console.timeEnd('perf')
# Memory leaks
node --expose-gc --max-old-space-size=4096 app.js
Python
# Built-in debugger
python -m pdb script.py
# Breakpoint in code
breakpoint() # Python 3.7+
# Verbose tracing
python -X tracemalloc script.py
# Profile
python -m cProfile -s cumulative script.py
Swift
# LLDB debugging
lldb ./MyApp
(lldb) breakpoint set --name main
(lldb) run
(lldb) po myVariable
# Xcode: Product → Profile (Instruments)
CSS / Layout
/* Outline all elements */
* { outline: 1px solid red !important; }
/* Debug specific element */
.debug { background: rgba(255,0,0,0.1) !important; }
Network
# HTTP debugging
curl -v https://api.example.com/endpoint
curl -w "@curl-format.txt" -o /dev/null -s https://example.com
# DNS
dig example.com
nslookup example.com
# Ports
lsof -i :3000
netstat -tlnp
Git Bisect
git bisect start
git bisect bad # Current commit is broken
git bisect good abc1234 # Known good commit
# Git checks out middle commit — test it, then:
git bisect good # or git bisect bad
# Repeat until root cause commit is found
git bisect reset
Common Error Patterns
| Error | Likely Cause | Fix |
|---|---|---|
Cannot read property of undefined |
Missing null check or wrong data shape | Add optional chaining (?.) or validate data |
ENOENT |
File/directory doesn't exist | Check path, create directory, use existsSync |
CORS error |
Backend missing CORS headers | Add CORS middleware with correct origins |
Module not found |
Missing dependency or wrong import path | npm install, check tsconfig paths |
Hydration mismatch (React) |
Server/client render different HTML | Ensure consistent rendering, use useEffect for client-only |
Segmentation fault |
Memory corruption, null pointer | Check array bounds, pointer validity |
Connection refused |
Service not running on expected port | Check if service is up, verify port/host |
Permission denied |
File/network permission issue | Check chmod, firewall, sudo |
Quick Diagnostic Commands
# What's using this port?
lsof -i :PORT
# What's this process doing?
ps aux | grep PROCESS
# Watch file changes
fswatch -r ./src
# Disk space
df -h
# System resource usage
top -l 1 | head -10
Debugging Mindset
- Don't assume — verify every assumption with evidence
- Change one thing at a time — multiple simultaneous changes make it impossible to know what fixed it
- Read error messages carefully — the answer is often right there
- Check logs first — before writing new instrumentation, read what's already recorded
- Simplify — create the smallest possible reproduction case
- Take breaks — fresh eyes catch what tired eyes miss
Example Session
Bug: "API returns 500 intermittently, can't reproduce locally"
Protocol:
- Reproduce: Check if it happens at specific times, with specific payloads, or at high load
- Isolate: Add request logging to capture failing payloads;
git bisectto find when it started - Hypothesize: Race condition in database connection? Timeout on external service call?
- Instrument: Add structured logging around the suspect area with request ID tracing
- Verify: Reproduce with captured payload; confirm stack trace matches hypothesis
- Fix: Add connection pooling / timeout handling / retry logic
- Test: Add integration test with the failing payload; verify it passes
Source: GPTtang/skill-atlas — distributed by TomeVault.