# Debug Mode

> 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.

- Skill: `majiayu000/debug-mode` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/debug-mode`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/debug-mode/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/debug-mode

---


# 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`

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

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

### Phase 3: Collect Logs

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

**Log Server (recommended):**
```bash
node ~/.claude/plugins/debug-mode/skills/debug-mode/scripts/log-server.js
```
Then app sends to `http://localhost:3333/log`

**Read logs:**
```bash
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

```bash
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