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.