tomevault-io Debugging Patterns Skill
Systematic problem-solving and error analysis.
The Debugging Mindset
- Reproduce — Can you make it happen consistently?
- Isolate — What's the smallest case that fails?
- Hypothesize — What could cause this?
- Test — Prove or disprove your hypothesis
- Fix — Change ONE thing
- Verify — Did it actually fix it?
Binary Search Debugging
When you don't know where the problem is:
1. Find a known-good state (commit, version, config)
2. Find the known-bad state (current)
3. Test the midpoint
4. Repeat until you find the breaking change
Git bisect automates this:
git bisect start
git bisect bad # Current is broken
git bisect good <known-good-sha> # This worked
# Git checks out midpoint, you test, then:
git bisect good # or git bisect bad
# Repeat until found
git bisect reset # Return to normal
Stack Trace Reading
Error: Cannot read property 'x' of undefined
at processData (src/utils.ts:45:12) ← LOOK HERE FIRST
at handleRequest (src/api.ts:123:8)
at Router.handle (node_modules/...)
Pattern: Read bottom-up for context, top-down for cause.
Common Error Categories
| Symptom | Likely Cause | Check |
|---|---|---|
| "undefined is not a function" | Wrong import/export | Module paths, named vs default |
| "Cannot find module" | Path or package issue | Relative paths, node_modules |
| "ENOENT" | File not found | Path typo, file doesn't exist |
| "EACCES" | Permission denied | File permissions, admin rights |
| Silently fails | Swallowed error | Add try/catch, check promises |
| Works locally, fails in CI | Environment diff | Env vars, paths, versions |
Logging Strategy
// Bad: console.log("here")
// Good: console.log("[processData] input:", data, "state:", state)
// Even better: structured logging
log.debug({ fn: 'processData', input: data, state }, 'Processing started');
Rubber Duck Debugging
When stuck:
- Explain the problem out loud (or in text)
- Describe what SHOULD happen
- Describe what ACTUALLY happens
- Walk through the code step by step
- Often, the explanation reveals the bug
Hypothesis Testing
Don't just change things randomly:
❌ "Let me try this... and this... and this..."
✅ "I think X is null because Y. Let me add a log to confirm."
Environment Debugging
# Check environment variables
$env:PATH
$env:NODE_ENV
# Check versions
node --version
npm --version
code --version
# Check what's installed
npm list --depth=0
Anti-Patterns
- ❌ Changing multiple things at once
- ❌ Assuming you know the cause without evidence
- ❌ Ignoring error messages
- ❌ "It works on my machine" without investigating why
- ❌ Removing error handling to "fix" errors
Synapses
See synapses.json for connections.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.