Initial commit

2025-11-30 09:00:21 +08:00
commit f5496428cd
50 changed files with 10011 additions and 0 deletions
--- a/commands/troubleshoot.md
+++ b/commands/troubleshoot.md
@@ -0,0 +1,110 @@
+---
+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