debug-mode

Remedy92's avatarfrom Remedy92

Autonomous debugging workflow mirroring Cursor IDE's debug mode. Triggers on "debug mode", "help me debug", error messages, stack traces, or debugging loops. Generates 5-7 hypotheses, narrows to top 2, adds strategic logs with [DEBUG:] prefix, collects logs via local server, analyzes, fixes, and cleans up.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 4, 2025
[Debugging]

When & Why to Use This Skill

The Debug Mode skill implements an autonomous, systematic debugging workflow for Claude, mirroring the advanced debugging capabilities of the Cursor IDE. It streamlines the troubleshooting process by automating hypothesis generation, strategic log insertion with a dedicated local server, and iterative analysis to identify and resolve complex software bugs efficiently.

Use Cases

  • Case 1: Resolving intermittent async race conditions by tracking execution order and timestamps using strategic [DEBUG:] logs.
  • Case 2: Fixing complex state management issues in frontend or backend applications by monitoring state mutations and data transformations.
  • Case 3: Troubleshooting API integration failures by capturing and analyzing real-time request/response bodies through a local log server.
  • Case 4: Identifying the root cause of 'undefined' or 'null' reference errors in large codebases using a structured 5-7 point hypothesis testing framework.
  • Case 5: Breaking out of unproductive 'debugging loops' where previous fix attempts have failed by enforcing a systematic analysis and verification phase.
namedebug-mode
descriptionAutonomous debugging workflow mirroring Cursor IDE's debug mode. Triggers on "debug mode", "help me debug", error messages, stack traces, or debugging loops. Generates 5-7 hypotheses, narrows to top 2, adds strategic logs with [DEBUG:] prefix, collects logs via local server, analyzes, fixes, and cleans up.

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

Bug Type Symptoms Log Focus
Type error TypeError, undefined Variable types/values
Async race Intermittent Timestamps, order
State bug Stale data Before/after mutations
API issue Bad response Request/response bodies
Null ref Cannot read property Object structure

Scripts

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