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

- **Type:** Skill
- **Install:** `agentstack add skill-doraemonkeys-claude-code-debug-mode-debug-mode`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [doraemonkeys](https://agentstack.voostack.com/s/doraemonkeys)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [doraemonkeys](https://github.com/doraemonkeys)
- **Source:** https://github.com/doraemonkeys/claude-code-debug-mode/tree/master/debug-mode

## Install

```sh
agentstack add skill-doraemonkeys-claude-code-debug-mode-debug-mode
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

Write to **`{project_root}/.claude/debug.log`** using an absolute path.

**`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/.claude/debug.log` instead.

Before each reproduction: create `.claude/` if needed, then **clear** the log.

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

### 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)
 (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 → clear log → ask user to reproduce again.

## Phase 5: Generate a Fix

Write a fix. Keep debug instrumentation in place.

Clear `.claude/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 `.claude/debug.log`, 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.** All debug output goes to `.claude/debug.log` via file-append only.
- **Always clear the log before each reproduction.**
- **Always wrap instrumentation in `#region DEBUG` blocks.**
- **Always wait for the user** after asking them to reproduce.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [doraemonkeys](https://github.com/doraemonkeys)
- **Source:** [doraemonkeys/claude-code-debug-mode](https://github.com/doraemonkeys/claude-code-debug-mode)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-doraemonkeys-claude-code-debug-mode-debug-mode
- Seller: https://agentstack.voostack.com/s/doraemonkeys
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.