ComputerConnection/debug

Debug Mode: $ARGUMENTS

Systematic debugging for when things aren't working.

---

Philosophy

You're a vibe coder - you learn by doing, not by reading docs. Debugging is the same: structured experimentation, not guessing.

The Loop:

1. Observe (what's actually happening?)
2. Hypothesize (what might cause this?)
3. Test (one thing at a time)
4. Learn (what did we discover?)
5. Repeat

---

Phase 1: Stabilize

Before debugging, capture the current state:

What's the symptom?

• [ ] Error message (exact text)
• [ ] Unexpected behavior (expected vs actual)
• [ ] Crash/hang
• [ ] Performance issue
• [ ] Something else

Can you reproduce it?

• [ ] Every time (good - easier to debug)
• [ ] Sometimes (note the pattern)
• [ ] Only once so far (try to reproduce first)

What changed recently?

• [ ] New code
• [ ] New dependency
• [ ] Config change
• [ ] Environment change
• [ ] Nothing obvious

---

Phase 2: Gather Evidence

Check the logs

# Recent terminal output
# Check browser console (F12)
# Check application logs

# For Node/npm:
npm run dev 2>&1 | tee debug.log

# For Tauri:
cd ~/nexus && npm run tauri:dev 2>&1 | tee debug.log

# System logs (if relevant):
journalctl -f

Check the error

• What's the exact error message?
• What file/line is mentioned?
• Is there a stack trace?

Check git

# What changed?
git diff
git log --oneline -10

# When did it last work?
git log --oneline

# Try previous commit
git stash
git checkout HEAD~1
# test
git checkout -
git stash pop

---

Phase 3: Isolate

Narrow down where the problem is:

The Halving Method

1. Find the middle of the suspected code
2. Add a log/breakpoint there
3. Does the problem happen before or after?
4. Repeat on that half
5. Keep halving until you find it

Binary Search Git

# If it worked before, find when it broke
git bisect start
git bisect bad                 # Current is broken
git bisect good <commit>       # Known good commit
# Git will checkout middle commits
# Test each one, mark good/bad
git bisect good  # or
git bisect bad
# Eventually finds the breaking commit
git bisect reset

Component Isolation

• Can you reproduce with minimal code?
• Does it happen in isolation or only with other components?
• Does it happen in a fresh environment?

---

Phase 4: Common Culprits

Check these first (they're usually the problem):

JavaScript/TypeScript

• [ ] Typo in variable/function name
• [ ] Missing await on async function
• [ ] Null/undefined access
• [ ] Wrong import path
• [ ] Stale cache (rm -rf node_modules && npm install)
• [ ] Type mismatch (check TypeScript errors)

React

• [ ] Missing dependency in useEffect
• [ ] Infinite re-render loop
• [ ] State not updating (mutation vs new object)
• [ ] Key prop issues in lists
• [ ] Stale closure

Tauri

• [ ] Command not registered in handler
• [ ] Rust panic (check terminal)
• [ ] IPC serialization mismatch
• [ ] Permission not granted
• [ ] Dev server not running

Network/API

• [ ] Wrong URL/endpoint
• [ ] CORS issue
• [ ] Auth token expired
• [ ] Request body format wrong
• [ ] Server not running

Environment

• [ ] Wrong Node version
• [ ] Missing env variable
• [ ] Port already in use
• [ ] File permissions
• [ ] Path issues

---

Phase 5: Debug Tools

Console/Print Debugging

// The classic
console.log('HERE 1');
console.log('value:', value);
console.log('type:', typeof value);
console.log('JSON:', JSON.stringify(value, null, 2));

Browser DevTools

• Console: errors and logs
• Network: API calls, responses
• Sources: breakpoints, step through
• React DevTools: component state

Node Debugging

# With inspector
node --inspect app.js
# Then open chrome://inspect

# Or use debugger statement
# Add `debugger;` in code, run with --inspect-brk

Rust/Tauri

// Print debugging
println!("Debug: {:?}", value);
dbg!(&value);

// Better: use tracing
tracing::info!("Something happened: {:?}", value);

---

Phase 6: Common Fixes

The Restart Ritual

# When in doubt, restart everything
# Kill dev servers
pkill -f "node"
pkill -f "vite"

# Clear caches
rm -rf node_modules/.cache
rm -rf .next
rm -rf dist

# Reinstall
rm -rf node_modules
npm install

# Restart
npm run dev

The Fresh Clone Test

# Nuclear option: does it work from scratch?
cd /tmp
git clone [your-repo]
cd [repo]
npm install
npm run dev

The Rollback

# Just go back to when it worked
git stash
git checkout <last-good-commit>
# Test. If works, diff to find what broke.

---

Phase 7: Document the Fix

Once fixed, capture it:

## Bug: [Description]

**Symptom**: [What was happening]

**Cause**: [Why it happened]

**Fix**: [What fixed it]

**Prevention**: [How to avoid in future]

Add to project's BUGS.md or similar.

---

When You're Stuck

1. Take a break - Fresh eyes find bugs faster
2. Rubber duck - Explain the problem out loud (to me, even)
3. Simplify - Remove code until it works, add back until it breaks
4. Ask - Describe what you've tried, I'll suggest next steps
5. Sleep on it - Seriously, this works

---

Debug Checklist

Before asking for help, verify:

• [ ] I can reproduce the issue
• [ ] I have the exact error message
• [ ] I know what changed recently
• [ ] I've checked the logs
• [ ] I've tried restarting/clearing caches
• [ ] I've isolated the problem area
• [ ] I've checked the common culprits

---

Output

1. Ask clarifying questions about the problem
2. Suggest specific diagnostic steps
3. Help interpret error messages
4. Propose fixes to try
5. Help document the solution