┌─────────────────────────────────────────────┐
│                                             │
│  1. Research → 2. Hypothesize → 3. Implement│
│       ↑                              ↓      │
│       │                              │      │
│       └──────── 5. Document ← 4. Test ──────│
│                     │                       │
│                     ↓                       │
│              (if not fixed, repeat)         │
│                                             │
└─────────────────────────────────────────────┘

Step Details

Step 1: Research

Before guessing, understand:

# Check existing research
Glob: resources/research/*.md
Glob: ideas/[project]/notes/research/*.md

# Search for similar issues in codebase
Grep: spaces/[project]/ for error message

# Check library docs via Context7
# WebSearch for error messages, known issues

Spawn research-specialist agent for:

Unfamiliar error messages
Library/framework behavior
Best practices for the pattern

Step 2: Hypothesize

Form ONE hypothesis:

Hypothesis: Query fires before auth state is set

Evidence:
- isLoading is true when query executes
- Error occurs only on initial load
- Works after manual refresh

Debug Plan:
1. Add console.log before query
2. Check auth state timing
3. Verify order of operations

Only one hypothesis at a time. Multiple theories = confusion.

Step 3: Implement

Apply fix + add debugging:

// Add liberal debug logging
console.log('[Auth] State before query:', authState);
console.log('[Query] Executing with user:', user?.id);

// Implement the fix
if (!authState.isReady) {
  console.log('[Query] Waiting for auth...');
  return;
}

Step 4: Test

Validate the fix:

cd spaces/[project]

# Run specific tests
npm test -- --grep "auth"

# Run full suite
npm test

# Manual verification if needed
npm run dev

NEVER claim "fixed" without tests passing.

Step 5: Document

Update WORKLOG with findings:

## YYYY-MM-DD - Troubleshooting Loop 1

**Hypothesis**: Query fires before auth state is set

**Debug findings**:
- isLoading was true when query executed
- Auth state not propagating to component
- Race condition between auth init and query

**Implementation**: Added auth state check before query

**Result**: ✓ Fixed - 47/47 tests passing

**Gotcha**: Auth state needs explicit ready check, not just truthy

If Not Fixed

Rollback changes: git checkout -- .
Document what you learned
Return to Step 1 with new information

Execution Modes

Mode 1: During TASK Implementation

/troubleshoot yourbench 001 "tests failing"

Read: TASK.md, PLAN.md, WORKLOG.md for context
Execute 5-step loop
Document in issue's WORKLOG.md
Continue with /implement when fixed

Mode 2: Standalone Debugging

/troubleshoot yourbench "login broken on Safari"

Investigate without issue context
Document findings
Suggest creating BUG issue if significant

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
Document everything for future reference

Workflow

/implement → (issue occurs) → /troubleshoot → /worklog → /implement

After fixing:

Add WORKLOG entry with findings
Continue implementation
Or create BUG issue if recurring problem

troubleshoot

/troubleshoot

Usage

The 5-Step Loop