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

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:

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: doraemonkeys/claude-code-debug-mode — distributed by TomeVault.