SuperClaude/.claude/commands/troubleshoot.md

@include shared/constants.yml#Process_Symbols

@include shared/command-templates.yml#Universal_Flags

Troubleshoot & resolve issues in code or system in $ARGUMENTS.

Thinking flags (optional):

• --think→multi-component debugging w/ context
• --think-hard→complex system issues & race conditions
• --ultrathink→critical prod issues or elusive bugs

Examples:

• /user:troubleshoot --investigate --think - Debug w/ full context
• /user:troubleshoot --five-whys --think-hard - Deep root cause analysis
• /user:troubleshoot --prod --ultrathink - Critical prod debugging

Mode selection:

--investigate flag:

• Focus→understanding & analyzing issue | Use debugging tools & techniques→gather info
• Document findings w/o necessarily impl fixes | Useful→complex problems requiring deep analysis

--fix flag:

• Complete full bug-fixing workflow | Create tests, impl solution & verify resolution
• Document the fix and prevention measures
• Default mode if no flag specified

When --five-whys flag is present:

• Apply root cause analysis methodology
• Ask "why" iteratively to uncover underlying causes
• Document each level of analysis
• Propose systemic improvements to prevent recurrence

When --prod flag is present:

• Focus on production-specific issues
• Analyze logs, monitoring data, and metrics
• Consider performance and scaling factors
• Ensure minimal disruption to live services
• Implement safe rollout strategies

Comprehensive troubleshooting workflow:

1. Reproduce & Understand

   • Create minimal reproduction steps
   • Document expected vs actual behavior
   • Identify affected components and users
   • Determine severity and business impact

2. Investigate & Isolate

   • Use debugging tools and strategic logging
   • Apply binary search to narrow problem scope
   • Check recent changes (git blame/history)
   • Analyze logs, stack traces, and monitoring data
   • Rule out environmental factors

3. Root Cause Analysis

   • Identify the underlying cause, not just symptoms
   • Use five-whys technique if needed
   • Consider systemic issues
   • Document contributing factors

4. Solution Development (if --fix flag)

   • Create failing test that reproduces the issue
   • Implement minimal fix addressing root cause
   • Ensure backward compatibility
   • Consider edge cases and side effects

5. Verification & Prevention

   • Verify fix resolves the issue completely
   • Run full test suite for regressions
   • Test in realistic conditions
   • Add monitoring for early detection
   • Document lessons learned

Investigation techniques:

• Strategic logging and breakpoints
• Performance profiling for bottlenecks
• Memory analysis for leaks
• Network inspection for API issues
• Database query analysis

For production issues:

• Correlate with deployment timeline
• Check for traffic patterns
• Review configuration changes
• Analyze resource utilization
• Consider rollback if critical

@include shared/command-templates.yml#Research_Requirements

@include shared/command-templates.yml#Report_Output

@include shared/constants.yml#Success_Messages