Bug Analyze

# Bug Analyze Command

Investigate and analyze the root cause of a reported bug.

## Usage

/bug-analyze [bug-name]

## Phase Overview

**Your Role**: Investigate the bug and identify the root cause

This is Phase 2 of the bug fix workflow. Your goal is to understand why the bug is happening and plan the fix approach.

## Instructions

You are working on the analysis phase of the bug fix workflow.

1. **Prerequisites**
   - Ensure report.md exists and is complete
   - Load the bug report for context
   - **Load steering documents**:
     - Check for .claude/steering/tech.md for technical patterns
     - Check for .claude/steering/structure.md for project organization
   - Understand the reported issue completely

2. **Investigation Process**
   1. **Code Investigation**
      - Search codebase for relevant functionality
      - Identify files, functions, and components involved
      - Map data flow and identify potential failure points
      - Look for similar issues or patterns

   2. **Root Cause Analysis**
      - Determine the underlying cause of the bug
      - Identify contributing factors
      - Understand why existing tests didn't catch this
      - Assess impact and risks

   3. **Solution Planning**
      - Design fix strategy
      - Consider alternative approaches
      - Plan testing approach
      - Identify potential risks

3. **Create Analysis Document**
   - Use the bug analysis template
   - Document investigation findings
   - Include specific code locations affected
   - Provide implementation plan for the fix

### Analysis Structure

```markdown
## Root Cause Analysis

- Investigation Summary: [What you found]
- Root Cause: [The underlying issue]
- Contributing Factors: [Secondary issues]

## Technical Details

- Affected Code Locations: [Specific files and functions]
- Data Flow Analysis: [How data moves and where it breaks]
- Dependencies: [External factors involved]

## Solution Approach

- Fix Strategy: [How to solve it]
- Alternative Solutions: [Other options considered]
- Implementation Plan: [Specific changes needed]

4. Investigation Guidelines

   • Follow tech.md standards: Understand existing patterns before proposing changes
   • Respect structure.md: Know where fixes should be placed
   • Search thoroughly: Look for existing utilities, similar bugs, related code
   • Think systematically: Consider data flow, error handling, edge cases
   • Plan for testing: How will you verify the fix works

5. Approval Process

   • Present the complete analysis document
   • Show code reuse opportunities: Note existing utilities that can help
   • Highlight integration points: Show how fix fits with existing architecture
   • Ask: "Does this analysis look correct? If so, we can proceed to implement the fix."
   • Incorporate feedback and revisions
   • Continue until explicit approval
   • CRITICAL: Do not proceed without explicit approval

Analysis Guidelines

Code Investigation

• Use search tools to find relevant code
• Understand existing error handling patterns
• Look for similar functionality that works correctly
• Check for recent changes that might have caused the issue

Root Cause Identification

• Don't just fix symptoms - find the real cause
• Consider edge cases and error conditions
• Look for design issues vs implementation bugs
• Understand the intended behavior vs actual behavior

Solution Design

• Prefer minimal, targeted fixes
• Reuse existing patterns and utilities
• Consider backwards compatibility
• Plan for future prevention of similar bugs

Critical Rules

• NEVER proceed to the next phase without explicit user approval
• Accept only clear affirmative responses: "yes", "approved", "looks good", etc.
• If user provides feedback, make revisions and ask for approval again
• Continue revision cycle until explicit approval is received

Next Phase

After approval, proceed to /bug-fix. ```