Debug Mode

Systematic debugging through hypothesis generation, strategic logging, and iterative analysis.

Activation Triggers

• “debug mode” or “enter debugger mode”
• “help me debug” or “fix this bug”
• Error messages or stack traces shared
• User stuck in debugging loop
• Previous fix attempts failed

Workflow

Phase 1: Hypothesize

Generate 5-7 possible causes, then narrow to top 2:

## Hypotheses (ranked)
1. [Most likely] ...
2. [Likely] ...
3. [Possible] ...

Consider: type errors, null/undefined, async timing, state bugs, API mismatches, imports, dependencies.

Phase 2: Add Logs

Insert strategic logs at:

• Function entry/exit
• Before/after data transforms
• API boundaries
• State mutations
• Conditional branches

Format: [DEBUG:location] description: value

console.log('[DEBUG:functionName] variable:', JSON.stringify(val, null, 2));

print(f'[DEBUG:function_name] variable: {val}')

Phase 3: Collect Logs

Terminal: npm run dev 2>&1 | tee debug.log

Log Server (recommended):

node ~/.claude/plugins/debug-mode/skills/debug-mode/scripts/log-server.js

Then app sends to http://localhost:3333/log

Read logs:

node ~/.claude/plugins/debug-mode/skills/debug-mode/scripts/read-logs.js --json

Phase 4: Analyze

## Log Analysis
- Expected: A → B → C
- Actual: A → B → ✗
- Divergence: After B, value was X not Y
- Root cause: [conclusion]

Phase 5: Fix & Verify

1. Implement fix
2. Run with logs still in place
3. Verify fix works
4. If not fixed → return to Phase 1

Phase 6: Cleanup

grep -rn "\[DEBUG:" --include="*.js" --include="*.ts" --include="*.py" .

Remove all [DEBUG: logs, run final verification.

Quick Patterns

Scripts

• scripts/log-server.js – HTTP server at :3333 for collecting logs
• scripts/read-logs.js – CLI to fetch/filter collected logs