debug-mode

majiayu000's avatarfrom majiayu000

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 Jan 5, 2026
[Debugging]

When & Why to Use This Skill

This Claude skill implements an autonomous, systematic debugging workflow inspired by Cursor IDE's debug mode. It streamlines the troubleshooting process by generating ranked hypotheses, injecting strategic [DEBUG:] logs, and utilizing a local server to capture and analyze runtime data for precise and efficient bug resolution.

Use Cases

  • Troubleshooting intermittent asynchronous race conditions by tracking execution order and timestamps with strategic logging.
  • Resolving complex state management issues in frontend or backend applications by monitoring data mutations before and after state changes.
  • Diagnosing API integration failures and mismatches by capturing real-time request and response payloads through a dedicated local log server.
  • Systematically narrowing down the root cause of 'undefined' or null reference errors in large, unfamiliar codebases using hypothesis-driven analysis.
  • Automating the cleanup of temporary debugging statements and performing final verification to ensure clean, production-ready code after a fix.
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