111 lines
3.4 KiB
Markdown
111 lines
3.4 KiB
Markdown
---
|
|
tags: ["debugging", "investigation", "problem-solving"]
|
|
description: "5-step debugging loop for unexpected issues during implementation or standalone bug fixes"
|
|
argument-hint: "[BUG-### | TASK-### | \"description\"]"
|
|
allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "WebSearch", "WebFetch", "Task"]
|
|
model: claude-sonnet-4-5
|
|
references_guidelines:
|
|
- docs/development/workflows/bug-workflow.md # 5-step debugging loop, reproduction-first approach
|
|
- docs/development/workflows/worklog-format.md # WORKLOG entry formats
|
|
---
|
|
|
|
# /troubleshoot Command
|
|
|
|
**WHAT**: Systematic debugging using the 5-step loop from bug-workflow.md.
|
|
|
|
**WHY**: Avoid shotgun debugging. Research first, one hypothesis at a time, validate before claiming fixed.
|
|
|
|
**HOW**: Follow the 5-step debugging loop in bug-workflow.md.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
/troubleshoot "tests failing after auth changes" # During TASK - describe the issue
|
|
/troubleshoot TASK-001 # Debug issue in specific task context
|
|
/troubleshoot BUG-007 # Equivalent to /implement BUG-007
|
|
```
|
|
|
|
## When to Use
|
|
|
|
| Situation | Command |
|
|
|-----------|---------|
|
|
| Unexpected issue during TASK implementation | `/troubleshoot "description"` or `/troubleshoot TASK-###` |
|
|
| Known bug with BUG.md created | `/troubleshoot BUG-###` or `/implement BUG-###` |
|
|
| Tests failing, unclear why | `/troubleshoot` |
|
|
|
|
## Execution
|
|
|
|
### Mode 1: During TASK Implementation
|
|
|
|
When something unexpected breaks while implementing a TASK:
|
|
|
|
1. **Read context**: Current TASK.md, PLAN.md, WORKLOG.md
|
|
2. **Execute 5-step loop** from bug-workflow.md
|
|
3. **Document** in current WORKLOG.md
|
|
4. **Continue** with TASK implementation
|
|
|
|
### Mode 2: Standalone Bug (BUG-###)
|
|
|
|
Equivalent to `/implement BUG-###`:
|
|
|
|
1. **Read context**: BUG.md, PLAN.md, WORKLOG.md
|
|
2. **Execute 5-step loop** from bug-workflow.md
|
|
3. **Document** in WORKLOG.md with root cause
|
|
4. **Complete** with `/complete BUG-###`
|
|
|
|
## The 5-Step Loop
|
|
|
|
**See bug-workflow.md for complete details.**
|
|
|
|
```
|
|
Research → Hypothesize → Implement → Test → Document
|
|
↑ │
|
|
└─────────── (if not fixed) ──────────────┘
|
|
```
|
|
|
|
### Quick Reference
|
|
|
|
1. **Research** - Context7 → docs → ask user (don't guess)
|
|
2. **Hypothesize** - ONE theory with debug plan
|
|
3. **Implement** - Fix + liberal debug logging
|
|
4. **Test** - Run tests, verify logs, confirm fix
|
|
5. **Document** - WORKLOG entry with hypothesis/findings/result
|
|
|
|
### Key Rules
|
|
|
|
- Research BEFORE guessing
|
|
- ONE hypothesis at a time
|
|
- Liberal debug logging (`console.log('[Component] State:', data)`)
|
|
- NEVER claim "fixed" without tests passing
|
|
- Rollback on failure before next attempt
|
|
|
|
## WORKLOG Entry
|
|
|
|
```markdown
|
|
## 2025-11-26 - Troubleshooting Loop 1
|
|
|
|
**Hypothesis:** Query fires before auth completes
|
|
|
|
**Debug findings:**
|
|
- isLoading was true when query executed
|
|
- Auth state not propagating to component
|
|
|
|
**Implementation:** Added auth state check
|
|
|
|
**Result:** ✓ Fixed - 47/47 tests passing
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
| Situation | Action |
|
|
|-----------|--------|
|
|
| Hypothesis fails | Rollback, document, return to Step 1 |
|
|
| 3+ failed loops | Pause, ask user for context |
|
|
| Tests pass but issue persists | More logging, manual verification |
|
|
|
|
## Integration
|
|
|
|
**During TASK:** Documents in current WORKLOG, returns to `/implement`
|
|
|
|
**For BUG:** Same as `/implement BUG-###`, follows bug-workflow.md
|