doraemonkeys/claude-code-debug-mode/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.).

Manual reproduction fatigues users—especially after 3+ rounds without finding the root cause. Include sufficiently detailed and reasonable debug information upfront to minimize reproduction cycles.

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, reproduce the bug yourself when the environment allows (run the failing command, tests, or endpoint). Only if you cannot reproduce it, tell the user how to reproduce, then STOP and wait.

Phase 4: Analyze Logs & Diagnose

When the bug has been reproduced (by you or the user):

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 → reproduce again yourself; ask the user only when you cannot.

Phase 5: Generate a Fix

Write a fix. Keep debug instrumentation in place.

Archive and reset .agents/debug.log, then reproduce again yourself to verify the fix. If you cannot reproduce it yourself, ask the user to verify, 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 the new logs; ask the user what they observed only if they were the one who reproduced. Return to Phase 2 and iterate.

Rules

• Never skip phases. Instrument and verify even if you think you know the answer.
• Never remove instrumentation until the fix is verified (by you, or by the user when you cannot reproduce it yourself).
• 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.