---
name: debug
description: Systematic bug debugging with deep analysis and resolution
argument-hint: <log|error|problem-description>
---

<objective>
Follow an ultra-deep analysis workflow to identify, understand, and resolve bugs.
**ULTRA THINK** at each phase transition.
</objective>

<quick_start>
```bash
/debug "NullReferenceException in UserService"
/debug paste the error log here
/debug why does login fail on mobile?
```
</quick_start>

<workflow>

## 1. ANALYZE: Deep Log/Error Analysis

- Parse the provided log/error message carefully
- Extract key error patterns, stack traces, and symptoms
- Identify error types: runtime, compile-time, logic, performance
- **CRITICAL**: Document exact error context and reproduction steps

## 2. EXPLORE: Targeted Codebase Investigation

Launch **parallel subagents** to search for error-related code:

**Agent 1: Codebase Search** (`explore-codebase`)
```
Find code related to this error: {error_description}
Search for:
- Error source location from stack trace
- Related error handling patterns
- Similar code that works correctly
Report file paths with line numbers.
```

**Agent 2: Documentation** (`explore-docs`)
```
Research documentation for: {libraries_in_stacktrace}
Find:
- Known issues or breaking changes
- Correct usage patterns
- Migration guides if version issues
```

**Agent 3: Web Research** (`websearch`)
```
Search for: {error_message}
Find:
- Similar issues reported by others
- Solutions and workarounds
- Root cause explanations
```

Additional investigation:
- Search for similar error patterns in codebase using Grep
- Find all files related to the failing component/module
- Examine recent changes that might have introduced the bug
- **ULTRA THINK**: Connect error symptoms to potential root causes

## 3. ULTRA-THINK: Deep Root Cause Analysis

**THINK DEEPLY** about the error chain: symptoms -> immediate cause -> root cause

Consider all possible causes:
- Code logic errors
- Configuration issues
- Environment problems
- Race conditions
- Memory issues
- Network problems

**CRITICAL**: Map the complete failure path from root cause to visible symptom
Validate hypotheses against the evidence

### WHY Technique

Ask "why" at least 5 times:
1. Why did the error occur? -> X happened
2. Why did X happen? -> Y was in invalid state
3. Why was Y invalid? -> Z didn't initialize properly
4. Why didn't Z initialize? -> A dependency was missing
5. Why was dependency missing? -> Configuration error

## 4. RESEARCH: Solution Investigation

Launch **parallel subagents** for solution research:

**Agent: Solution Search** (`websearch`)
```
Search for solutions to: {root_cause}
Find:
- Recommended fixes
- Best practices
- Workarounds if fix is complex
```

Evaluate solutions:
- Search for similar issues and solutions online
- Check documentation for affected libraries/frameworks
- Look for known bugs, workarounds, and best practices
- **THINK**: Evaluate solution approaches for this specific context

## 5. IMPLEMENT: Systematic Resolution

- Choose the most appropriate solution based on analysis
- Follow existing codebase patterns and conventions
- Implement minimal, targeted fixes
- **STAY IN SCOPE**: Fix only what's needed for this specific bug
- Add defensive programming where appropriate

## 6. VERIFY: Comprehensive Testing

- Test the specific scenario that was failing
- Run related tests to ensure no regressions
- Check edge cases around the fix
- **CRITICAL**: Verify the original error is completely resolved

</workflow>

<analysis_techniques>

### Log Analysis
- Extract timestamps, error codes, stack traces
- Identify error propagation patterns
- Look for correlation with system events

### Code Investigation
- Trace execution path to error location
- Check variable states and data flow
- Examine error handling patterns
- Review recent commits affecting the area

### Root Cause Mapping
- **WHY technique**: Ask "why" 5 times minimum
- Consider environmental factors
- Check for timing/concurrency issues
- Validate assumptions about data/state

</analysis_techniques>

<execution_rules>

- **ULTRA THINK** at each phase transition
- Use parallel agents for comprehensive investigation
- Document findings and reasoning at each step
- **NEVER guess** - validate all hypotheses with evidence
- **MINIMAL CHANGES**: Fix root cause, not symptoms
- Test thoroughly before declaring resolution complete

</execution_rules>

<priority>
Understanding > Speed > Completeness. Every bug must be fully understood before attempting fixes.
</priority>
