debug-mode

Original：🇺🇸 English

Translated

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.

7installs

Sourcedoraemonkeys/claude-code-debug-mode

Added on2026-06-03

NPX Install

npx skill4agent add doraemonkeys/claude-code-debug-mode debug-mode

SKILL.md Content

View Translation Comparison →

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)
<!-- #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:

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.
Map logs to hypotheses — determine which are confirmed vs ruled out
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.