debug-mode

Name: debug-mode
Author: doraemonkeys

107stars6forks

How to install debug-mode?

doraemonkeys/claude-code-debug-mode/debug-mode

$npx -y skills add doraemonkeys/claude-code-debug-mode --skill debug-mode

Installs into the current project.

Summary

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 t

Files · 1

View on GitHub

SKILL.md

1	# Debug Mode
2
3	You are in Debug Mode — a hypothesis-driven debugging workflow. Do NOT jump to fixes. Follow each phase in order.
4
5	---
6
7	## Phase 1: Understand the Bug
8
9	Ask the user (if not already provided): expected vs actual behavior, reproduction steps, error messages.
10
11	Read the relevant source code. Understand the call chain and data flow.
12
13	## Phase 2: Generate Hypotheses
14
15	Generate testable hypotheses as a numbered list:
16
17	```
18	Based on my analysis, here are my hypotheses:
19
20	1. [Title] — [What might be wrong and why]
21	2. [Title] — [Explanation]
22	3. [Title] — [Explanation]
23	```
24
25	Include both obvious and non-obvious causes (race conditions, off-by-one, stale closures, type coercion, etc.).
26
27	## Phase 3: Instrument the Code
28
29	### Log file
30
31	Write to `{project_root}/.claude/debug.log` using an absolute path.
32
33	`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.
34
35	Before each reproduction: create `.claude/` if needed, then clear the log.
36
37	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).
38
39	### Region markers
40
41	ALL instrumentation MUST be wrapped in region blocks for clean removal:
42
43	```
44	// #region DEBUG (JS/TS/Java/C#/Go/Rust/C/C++)
45	# #region DEBUG (Python/Ruby/Shell/YAML)
46	<!-- #region DEBUG --> (HTML/Vue/Svelte)
47	-- #region DEBUG (Lua)
48
49	...instrumentation...
50
51	// #endregion DEBUG (matching closer)
52	```
53
54	### Logging rules
55
56	- 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.
57	- Log messages include hypothesis number: `[DEBUG H1]`, `[DEBUG H2]`, etc.
58	- Log variable states, execution paths, timing, decision points
59	- Be minimal — only what's needed to confirm/rule out each hypothesis
60
61	After instrumenting, tell the user to reproduce the bug, then STOP and wait.
62
63	## Phase 4: Analyze Logs & Diagnose
64
65	When the user has reproduced:
66
67	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.
68	2. Map logs to hypotheses — determine which are confirmed vs ruled out
69	3. Present diagnosis with evidence:
70
71	```
72	## Diagnosis
73
74	Root cause: [Explanation backed by log evidence]
75
76	Evidence:
77	- [H1] Ruled out — [why]
78	- [H2] Confirmed — [log evidence]
79	```
80
81	If inconclusive: new hypotheses → more instrumentation → clear log → ask user to reproduce again.
82
83	## Phase 5: Generate a Fix
84
85	Write a fix. Keep debug instrumentation in place.
86
87	Clear `.claude/debug.log`, ask user to verify the fix works, then STOP and wait.
88
89	## Phase 6: Verify & Clean Up
90
91	If fixed: Remove all `#region DEBUG` blocks and contents (use Grep to find them), delete `.claude/debug.log`, summarize.
92
93	If NOT fixed: Read new logs, ask what they observed, return to Phase 2, iterate.
94
95	---
96
97	## Rules
98
99	- Never skip phases. Instrument and verify even if you think you know the answer.
100	- Never remove instrumentation before user confirms the fix.
101	- Never use `console.log`、`print` etc. All debug output goes to `.claude/debug.log` via file-append only.
102	- Always clear the log before each reproduction.
103	- Always wrap instrumentation in `#region DEBUG` blocks.
104	- Always wait for the user after asking them to reproduce.

People who liked this also viewed

6 picks

Type

debug-mode

107stars6forks

View on GitHub

How to install debug-mode?

doraemonkeys/claude-code-debug-mode/debug-mode

$npx -y skills add doraemonkeys/claude-code-debug-mode --skill debug-mode

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Debug Mode
2
3	You are in Debug Mode — a hypothesis-driven debugging workflow. Do NOT jump to fixes. Follow each phase in order.
4
5	---
6
7	## Phase 1: Understand the Bug
8
9	Ask the user (if not already provided): expected vs actual behavior, reproduction steps, error messages.
10
11	Read the relevant source code. Understand the call chain and data flow.
12
13	## Phase 2: Generate Hypotheses
14
15	Generate testable hypotheses as a numbered list:
16
17	```
18	Based on my analysis, here are my hypotheses:
19
20	1. [Title] — [What might be wrong and why]
21	2. [Title] — [Explanation]
22	3. [Title] — [Explanation]
23	```
24
25	Include both obvious and non-obvious causes (race conditions, off-by-one, stale closures, type coercion, etc.).
26
27	## Phase 3: Instrument the Code
28
29	### Log file
30
31	Write to `{project_root}/.claude/debug.log` using an absolute path.
32
33	`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.
34
35	Before each reproduction: create `.claude/` if needed, then clear the log.
36
37	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).
38
39	### Region markers
40
41	ALL instrumentation MUST be wrapped in region blocks for clean removal:
42
43	```
44	// #region DEBUG (JS/TS/Java/C#/Go/Rust/C/C++)
45	# #region DEBUG (Python/Ruby/Shell/YAML)
46	<!-- #region DEBUG --> (HTML/Vue/Svelte)
47	-- #region DEBUG (Lua)
48
49	...instrumentation...
50
51	// #endregion DEBUG (matching closer)
52	```
53
54	### Logging rules
55
56	- 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.
57	- Log messages include hypothesis number: `[DEBUG H1]`, `[DEBUG H2]`, etc.
58	- Log variable states, execution paths, timing, decision points
59	- Be minimal — only what's needed to confirm/rule out each hypothesis
60
61	After instrumenting, tell the user to reproduce the bug, then STOP and wait.
62
63	## Phase 4: Analyze Logs & Diagnose
64
65	When the user has reproduced:
66
67	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.
68	2. Map logs to hypotheses — determine which are confirmed vs ruled out
69	3. Present diagnosis with evidence:
70
71	```
72	## Diagnosis
73
74	Root cause: [Explanation backed by log evidence]
75
76	Evidence:
77	- [H1] Ruled out — [why]
78	- [H2] Confirmed — [log evidence]
79	```
80
81	If inconclusive: new hypotheses → more instrumentation → clear log → ask user to reproduce again.
82
83	## Phase 5: Generate a Fix
84
85	Write a fix. Keep debug instrumentation in place.
86
87	Clear `.claude/debug.log`, ask user to verify the fix works, then STOP and wait.
88
89	## Phase 6: Verify & Clean Up
90
91	If fixed: Remove all `#region DEBUG` blocks and contents (use Grep to find them), delete `.claude/debug.log`, summarize.
92
93	If NOT fixed: Read new logs, ask what they observed, return to Phase 2, iterate.
94
95	---
96
97	## Rules
98
99	- Never skip phases. Instrument and verify even if you think you know the answer.
100	- Never remove instrumentation before user confirms the fix.
101	- Never use `console.log`、`print` etc. All debug output goes to `.claude/debug.log` via file-append only.
102	- Always clear the log before each reproduction.
103	- Always wrap instrumentation in `#region DEBUG` blocks.
104	- Always wait for the user after asking them to reproduce.

People who liked this also viewed

6 picks

Type