/troubleshoot

Systematic debugging using a 5-step loop: Research → Hypothesize → Implement → Test → Document.

Usage

/troubleshoot yourbench "tests failing after auth changes" /troubleshoot yourbench 001 # Debug in context of issue /troubleshoot coordinatr # General debugging session

The 5-Step Loop

┌─────────────────────────────────────────────┐ │ │ │ 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