Auto mode (fully automatic, use recommended solutions):
/debug -a API returning 500 on POST
What it does:
- Analyze: Reproduce error, identify root cause → ask if you have more context
- Log Technique (if needed): Add debug logs → user runs & shares output → analyze
- Find Solutions: Research 2-3+ potential fixes with pros/cons
- Propose: Present options → you choose which solution
- Fix: Implement solution with strategic logging
- Verify: Multi-layer verification (Static → Build → Runtime)
Key principle: Tests passing ≠ fix working. Always execute the actual code path.
Log Technique: When the error can't be reproduced, strategic debug logs are added. The user runs the app and shares the console output for analysis.
- Reproduce Before Anything Else - If you can't reproduce it, you can't verify the fix
- Hypothesis-Driven Analysis - List 3-5 causes ranked by likelihood, test systematically
- Multi-Layer Verification - Tests alone give false confidence (20-40% still fail in production)
┌─────────────┐
│ Manual │ ← User confirms
└──────┬──────┘
┌─────────┴─────────┐
│ Runtime Execution │ ← CRITICAL: Real execution
└─────────┬─────────┘
┌───────────┴───────────┐
│ Automated Checks │ ← Build, Types, Lint, Tests
└───────────┬───────────┘
┌─────────────┴─────────────┐
│ Static Analysis │ ← Syntax, Imports
└───────────────────────────┘
Key Insight: Tests passing ≠ fix working. ALWAYS execute the actual code path.
| Flag |
Name |
Description |
-a, --auto |
Auto mode |
Full automatic mode - don't ask the user, use recommended solutions |
Arguments:
- Everything after flags =
{error_context} - Description of the error or context about what's failing
| Variable |
Type |
Description |
{error_context} |
string |
User's description of the error |
{auto_mode} |
boolean |
Skip confirmations, use recommended options |
{error_analysis} |
object |
Detailed analysis from step 1 |
{debug_logs} |
list |
Debug logs added for cleanup (file, line, prefix) |
{solutions} |
list |
Potential solutions found in step 2 |
{selected_solution} |
object |
User's chosen solution from step 3 |
{files_modified} |
list |
Files changed during the fix |
{verification_result} |
object |
Results from verification step |
|
|
|
1---2name: debug-53description: Systematic error debugging with analysis, solution discovery, and verification4---5
6<objective>
7Debug errors systematically through a 5-step workflow: analyze the error, find potential solutions, propose options to the user, implement the fix, and verify it works through multi-layer verification.
8</objective>
9
10<quick_start>
11**Debug an error (interactive):**
12```bash
13/debug login page crashes on submit
14```
15
16**Auto mode (fully automatic, use recommended solutions):**
17```bash
18/debug -a API returning 500 on POST
19```
20
21**What it does:**
221. **Analyze**: Reproduce error, identify root cause → **ask if you have more context**
232. **Log Technique** (if needed): Add debug logs → **user runs & shares output** → analyze
243. **Find Solutions**: Research 2-3+ potential fixes with pros/cons
254. **Propose**: Present options → **you choose which solution**
265. **Fix**: Implement solution with strategic logging
276. **Verify**: Multi-layer verification (Static → Build → Runtime)
28
29**Key principle**: Tests passing ≠ fix working. Always execute the actual code path.
30
31**Log Technique**: When the error can't be reproduced, strategic debug logs are added. The user runs the app and shares the console output for analysis.
32</quick_start>
33
34<methodology>
35<core_principles>
36**Battle-Tested Principles:**
37
381. **Reproduce Before Anything Else** - If you can't reproduce it, you can't verify the fix
392. **Hypothesis-Driven Analysis** - List 3-5 causes ranked by likelihood, test systematically
403. **Multi-Layer Verification** - Tests alone give false confidence (20-40% still fail in production)
41</core_principles>
42
43<verification_pyramid>
44**Verification Pyramid:**
45
46```
47 ┌─────────────┐
48 │ Manual │ ← User confirms
49 └──────┬──────┘
50 ┌─────────┴─────────┐
51 │ Runtime Execution │ ← CRITICAL: Real execution
52 └─────────┬─────────┘
53 ┌───────────┴───────────┐
54 │ Automated Checks │ ← Build, Types, Lint, Tests
55 └───────────┬───────────┘
56 ┌─────────────┴─────────────┐
57 │ Static Analysis │ ← Syntax, Imports
58 └───────────────────────────┘
59```
60
61**Key Insight**: Tests passing ≠ fix working. ALWAYS execute the actual code path.
62</verification_pyramid>
63</methodology>
64
65<parameters>
66**Flags:**
67
68| Flag | Name | Description |
69|------|------|-------------|
70| `-a`, `--auto` | Auto mode | Full automatic mode - don't ask the user, use recommended solutions |
71
72**Arguments:**
73- Everything after flags = `{error_context}` - Description of the error or context about what's failing
74</parameters>
75
76<state_variables>
77**Persist throughout all steps:**
78
79| Variable | Type | Description |
80|----------|------|-------------|
81| `{error_context}` | string | User's description of the error |
82| `{auto_mode}` | boolean | Skip confirmations, use recommended options |
83| `{error_analysis}` | object | Detailed analysis from step 1 |
84| `{debug_logs}` | list | Debug logs added for cleanup (file, line, prefix) |
85| `{solutions}` | list | Potential solutions found in step 2 |
86| `{selected_solution}` | object | User's chosen solution from step 3 |
87| `{files_modified}` | list | Files changed during the fix |
88| `{verification_result}` | object | Results from verification step |
89</state_variables>
90
91<entry_point>
92Load `steps/step-00-init.md`
93</entry_point>
94
95<step_files>
96| Step | File | Description |
97|------|------|-------------|
98| 0 | `step-00-init.md` | Parse flags, setup state |
99| 1 | `step-01-analyze.md` | Reproduce error, form hypotheses, identify root cause |
100| 1b | `step-01b-log-instrumentation.md` | *Optional*: Add debug logs, user runs & shares output |
101| 2 | `step-02-find-solutions.md` | Research 2-3+ solutions with pros/cons |
102| 3 | `step-03-propose.md` | Present solutions for user selection |
103| 4 | `step-04-fix.md` | Implement with strategic logging |
104| 5 | `step-05-verify.md` | Multi-layer verification (Static → Build → Runtime → User) |
105</step_files>
106
107<references>
108| File | Description |
109|------|-------------|
110| `references/log-technique.md` | Log placement patterns, prefixes, security guidelines |
111</references>
112
113<success_criteria>
114- Error successfully reproduced
115- Root cause identified through hypothesis testing
116- 2-3+ potential solutions researched with pros/cons
117- Solution selected (by user or auto mode)
118- Fix implemented with strategic logging
119- Static analysis passes (syntax, imports)
120- Build completes successfully
121- Tests pass (if tests exist)
122- **Runtime execution verified** (actual code path executed)
123- User confirms fix resolves the original issue
124- No regressions introduced
125</success_criteria>
majiayu000