# Debug Mode

> Interactive debugging mode that generates hypotheses, instruments code with runtime logs, and iteratively fixes bugs with human-in-the-loop verification. Only for hard-to-diagnose bugs; in those cases, remind the user that debug-mode is available, and never proactively activate this skill.

- Skill: `doraemonkeys/debug-mode` (Agent Skill)
- Install (CLI): `npx skillmds@latest add doraemonkeys/debug-mode`
- Raw SKILL.md: https://api.skillmd.com/api/skills/doraemonkeys/debug-mode/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: doraemonkeys (https://skillmd.com/u/doraemonkeys)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/doraemonkeys/debug-mode

---


# Debug Mode

You are in **Debug Mode** — a hypothesis-driven debugging workflow. Do NOT jump to fixes. Follow each phase in order.

---

## Phase 1: Understand the Bug

Ask the user (if not already provided): expected vs actual behavior, reproduction steps, error messages.

Read the relevant source code. Understand the call chain and data flow.

## Phase 2: Generate Hypotheses

Generate **testable hypotheses** as a numbered list:

```
Based on my analysis, here are my hypotheses:

1. **[Title]** — [What might be wrong and why]
2. **[Title]** — [Explanation]
3. **[Title]** — [Explanation]
```

Include both obvious and non-obvious causes (race conditions, off-by-one, stale closures, type coercion, etc.).

## Phase 3: Instrument the Code

### Log file & Evidence Collection

Write to **`{project_root}/.agents/debug.log`** using an absolute path by default.

**`project_root` = hardcoded constant string** inferred from context (file paths in the conversation). PROHIBITED: `import.meta.dir`, `__dirname`, `process.cwd()`, `Deno.cwd()`, `path.resolve()` or any runtime detection. Exception: remote/CI environments or non-writable local filesystem — use `/tmp/.agents/debug.log` instead.

Before each reproduction: create `.agents/` if needed. If `.agents/debug.log` exists and is non-empty, **archive it first** (rename to `debug-1.log`, `debug-2.log`, etc., incrementing sequentially) before resetting `debug.log` to empty, preserving historical logs.

Server-side: file-append API (`fs.appendFileSync`, `open("a")`, etc.). Browser-side: `fetch` POST to a debug API route. **Must work in all environments** (dev/release).

**Adapt for non-standard environments & intermittent bugs (Evidence over Ritual):**

- **Restricted/remote/mobile runtimes:** If the code runs on mobile, embedded, or remote environments that cannot write to the project root, adapt the log destination (e.g. device storage, remote endpoint, or memory buffer) and ask the user to provide/paste the logs.
- **Intermittent bugs:** If the bug cannot be triggered immediately, keep instrumentation in place and let the user report back with logs whenever the issue occurs.

### Region markers

ALL instrumentation MUST be wrapped in region blocks for clean removal:

```
// #region DEBUG       (JS/TS/Java/C#/Go/Rust/C/C++)
# #region DEBUG        (Python/Ruby/Shell/YAML)
<!-- #region DEBUG --> (HTML/Vue/Svelte)
-- #region DEBUG       (Lua)

...instrumentation...

// #endregion DEBUG    (matching closer)
```

### Logging rules

- **NEVER use `console.log`、`print` or any stdout/stderr output.** All debug output MUST go to `debug.log` — server-side via file-append, browser-side via `fetch` to a debug API endpoint.
- Log messages include hypothesis number: `[DEBUG H1]`, `[DEBUG H2]`, etc.
- Log variable states, execution paths, timing, decision points
- Be minimal — only what's needed to confirm/rule out each hypothesis

After instrumenting, tell the user to reproduce the bug, then **STOP and wait**.

## Phase 4: Analyze Logs & Diagnose

When the user has reproduced:

1. **Check log file size first** (e.g. `wc -l` or `ls -lh`). If the log is large, use `tail` or `grep "[DEBUG H"` to extract only the relevant lines instead of reading the entire file — avoid flooding the context window.
2. Map logs to hypotheses — determine which are **confirmed** vs **ruled out**
3. Present diagnosis with evidence:

```
## Diagnosis

**Root cause**: [Explanation backed by log evidence]

Evidence:
- [H1] Ruled out — [why]
- [H2] Confirmed — [log evidence]
```

If inconclusive: new hypotheses → more instrumentation → archive & reset log → ask user to reproduce again.

## Phase 5: Generate a Fix

Write a fix. Keep debug instrumentation in place.

Archive and reset `.agents/debug.log`, ask user to verify the fix works, then **STOP and wait**.

## Phase 6: Verify & Clean Up

**If fixed:** Remove all `#region DEBUG` blocks and contents (use Grep to find them), delete all `.agents/debug*.log` files (including archived logs), summarize.

**If NOT fixed:** Read new logs, ask what they observed, return to **Phase 2**, iterate.

---

## Rules

- **Never skip phases.** Instrument and verify even if you think you know the answer.
- **Never remove instrumentation before user confirms the fix.**
- **Never use `console.log`、`print` etc.** Route all debug output to `{project_root}/.agents/debug.log` (or adapt the transport if runtime constraints require it).
- **Always archive existing logs and reset `debug.log` before each reproduction.**
- **Always wrap instrumentation in `#region DEBUG` blocks.**
- **Always wait for the user** after asking them to reproduce (or when waiting for intermittent occurrences).