debug

When invoked:

1. Capture the error — message, stack trace, logs, reproduction steps
2. Form 2-3 hypotheses ranked by likelihood
3. Test the most likely hypothesis first with the smallest possible investigation
4. Implement the minimal fix once root cause is confirmed
5. Add a regression test
6. Run the full test suite to verify nothing else broke

Debugging Process

1. Reproduce

• Get the exact error message and stack trace
• Identify the trigger — what input, action, or timing causes it
• Determine if it's consistent or intermittent
• Check recent changes: git log --oneline -20 and git diff HEAD~5

2. Isolate

• Trace execution from trigger to failure
• Narrow to the specific file, function, and line
• Read the failing code and its immediate dependencies

3. Diagnose

Document each hypothesis:

Hypothesis: [what you think is wrong]
Evidence for: [what supports this]
Evidence against: [what contradicts this]
Test: [smallest action to confirm or eliminate]
Result: [what happened]

4. Fix

• Minimal change addressing the root cause — not the symptom
• Check for the same pattern elsewhere in the codebase
• Add a test that would have caught this bug

Language-Specific Diagnostics

Go

go test -v -run TestName ./path/to/package     # Specific test
go test -race ./...                             # Race detection
go vet ./...                                    # Static analysis
GODEBUG=gctrace=1 ./binary                     # GC diagnostics

Common bugs: nil pointer dereference, goroutine leak (missing context cancellation), data race (shared state without sync), slice mutation (shared backing array), interface nil check ((*MyError)(nil) is not nil).

TypeScript / Bun

bun test --filter "test name"                   # Specific test
node --inspect src/index.ts                     # Debugger
DEBUG=* bun run dev                             # Verbose logging

Common bugs: unhandled promise rejection (missing await), type assertion masking null, stale closure, event loop blocking, import order side effects.

PostgreSQL

psql -c "SELECT * FROM pg_stat_activity WHERE state = 'active';"   # Active queries
psql -c "EXPLAIN ANALYZE <query>;"                                  # Query plan
psql -c "SELECT * FROM pg_locks WHERE NOT granted;"                 # Blocked locks

Common bugs: deadlock (inconsistent lock ordering), N+1 queries, missing index, transaction holding locks during external calls, RLS policy blocking.

Completion Criteria

• Root cause identified with evidence
• Fix is minimal and targeted
• Regression test added
• Full test suite passes