gh-taylorhuston-ai-toolkit-plugins-ai-toolkit/commands/troubleshoot.md

tags, description, argument-hint, allowed-tools, model, references_guidelines

tags	description	argument-hint	allowed-tools	model	references_guidelines
debugging investigation problem-solving	5-step debugging loop for unexpected issues during implementation or standalone bug fixes	[BUG-### | TASK-### | "description"]	Read Write Edit Bash Grep Glob WebSearch WebFetch Task	claude-sonnet-4-5	docs/development/workflows/bug-workflow.md docs/development/workflows/worklog-format.md

/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

/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

## 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