# Debug

> Systematic error debugging with analysis, solution discovery, and verification

- Skill: `majiayu000/debug-5` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/debug-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/debug-5/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/debug-5

---


<objective>
Debug 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.
</objective>

<quick_start>
**Debug an error (interactive):**
```bash
/debug login page crashes on submit
```

**Auto mode (fully automatic, use recommended solutions):**
```bash
/debug -a API returning 500 on POST
```

**What it does:**
1. **Analyze**: Reproduce error, identify root cause → **ask if you have more context**
2. **Log Technique** (if needed): Add debug logs → **user runs & shares output** → analyze
3. **Find Solutions**: Research 2-3+ potential fixes with pros/cons
4. **Propose**: Present options → **you choose which solution**
5. **Fix**: Implement solution with strategic logging
6. **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.
</quick_start>

<methodology>
<core_principles>
**Battle-Tested Principles:**

1. **Reproduce Before Anything Else** - If you can't reproduce it, you can't verify the fix
2. **Hypothesis-Driven Analysis** - List 3-5 causes ranked by likelihood, test systematically
3. **Multi-Layer Verification** - Tests alone give false confidence (20-40% still fail in production)
</core_principles>

<verification_pyramid>
**Verification Pyramid:**

```
        ┌─────────────┐
        │   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.
</verification_pyramid>
</methodology>

<parameters>
**Flags:**

| 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
</parameters>

<state_variables>
**Persist throughout all steps:**

| 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 |
</state_variables>

<entry_point>
Load `steps/step-00-init.md`
</entry_point>

<step_files>
| Step | File | Description |
|------|------|-------------|
| 0 | `step-00-init.md` | Parse flags, setup state |
| 1 | `step-01-analyze.md` | Reproduce error, form hypotheses, identify root cause |
| 1b | `step-01b-log-instrumentation.md` | *Optional*: Add debug logs, user runs & shares output |
| 2 | `step-02-find-solutions.md` | Research 2-3+ solutions with pros/cons |
| 3 | `step-03-propose.md` | Present solutions for user selection |
| 4 | `step-04-fix.md` | Implement with strategic logging |
| 5 | `step-05-verify.md` | Multi-layer verification (Static → Build → Runtime → User) |
</step_files>

<references>
| File | Description |
|------|-------------|
| `references/log-technique.md` | Log placement patterns, prefixes, security guidelines |
</references>

<success_criteria>
- Error successfully reproduced
- Root cause identified through hypothesis testing
- 2-3+ potential solutions researched with pros/cons
- Solution selected (by user or auto mode)
- Fix implemented with strategic logging
- Static analysis passes (syntax, imports)
- Build completes successfully
- Tests pass (if tests exist)
- **Runtime execution verified** (actual code path executed)
- User confirms fix resolves the original issue
- No regressions introduced
</success_criteria>