@endgame-build/claude-workflows/.claude/commands/eg/debug.md

Claude Code workflow system with commands, agents, and templates for AI-native development

---
description: Systematically identify and resolve issues
argument-hint: <instance-name> <description of bug>
---

# /eg:debug

You are tasked with systematically investigating and identifying the root cause of a bug or issue, then documenting findings and proposing a solution.

Input: `$ARGUMENTS`

## Step 1: Parse Arguments and Initialize

Parse the arguments to extract:
- Instance name (first word before space)
- Bug description (everything after first space)

Initialize debug session:
```
!mkdir -p .eg/{instance-name}
```

## Step 2: Investigate the Issue

Use the Task tool to systematically debug:

```
Task(
  description="Debug and find root cause",
  prompt=`
    Systematically investigate this issue: {bug-description}
    
    Use the solution template from .claude/templates/solution.template.md
    
    Investigation approach:
    1. Document symptoms and reproduction steps
    2. Add strategic logging to trace execution
    3. Use grep/search to find error origins
    4. Analyze data flow and state changes
    5. Check for race conditions or timing issues
    6. Review recent changes that might have introduced the bug
    7. Consider edge cases and error handling
    
    Use all available tools:
    - Logging and debugging utilities
    - Search tools for error patterns
    - MCPs for complex analysis
    
    Document in the solution template:
    - Problem Description: Clear summary of the issue
    - Root Cause: Specific cause identified through investigation
    - Evidence: Logs, traces, and findings that support the diagnosis
    - Solution Approach: Minimal fix that addresses the root cause
    - Implementation: Specific changes needed
    - Testing: How to verify the fix works
    - Impact: What else might be affected
    - Prevention: How to avoid similar issues
    
    Save findings to: .eg/{instance-name}/debug-analysis.md
    And solution to: .eg/{instance-name}/solution.md
  `,
  subagent_type="debugger"
)
```

## Step 3: Document Debug Session

Create a debug log with findings:

```
!echo "Debug Session: {bug-description}
Date: $(date)
Instance: {instance-name}

Symptoms:
{symptoms}

Root Cause:
{root-cause}

Evidence:
{evidence}

Next Steps:
- Review debug-analysis.md for full investigation
- Review solution.md for proposed fix
- Run: /eg:implement {instance-name} @.eg/{instance-name}/solution.md
" > .eg/{instance-name}/debug-summary.md
```

## Step 4: Validate Findings

If the root cause is identified with high confidence:
- Ensure the proposed solution is minimal and targeted
- Consider regression risks
- Document any areas that need extra testing

If root cause is unclear:
- Document what was ruled out
- Suggest additional investigation steps
- Consider involving domain experts

## Step 5: Phase Gate and Next Steps

### Phase Gate - Root Cause Confirmation

Present the debug findings and ask for explicit approval:
"Root cause analysis complete. The issue appears to be: {root-cause-summary}. Do you agree with this analysis? (yes/no)"

Based on response:
- If yes: "Ready to implement the fix. Use: `/eg:implement {instance-name} @.eg/{instance-name}/solution.md`"
- If no: "What aspects of the analysis should we revisit or what additional information can you provide?"

Alternative outcomes:
- If root cause unclear: "Unable to identify root cause definitively. Would you like to: a) Continue investigation with specific focus, b) Escalate to senior developer, c) Try a different debugging approach?"
- If external help needed: "This issue may require domain expertise in {area}. Should we proceed with partial fix or wait for expert input?"

The debug analysis and solution documents should provide everything needed to fix the issue efficiently.