# Debug Tool - Expert Debugging Assistant

**Root cause analysis for complex problems**

The `debug` tool provides systematic debugging assistance with root cause analysis, hypothesis generation, and structured problem-solving approaches for complex technical issues.

## Thinking Mode

**Default is `medium` (8,192 tokens).** Use `high` for tricky bugs (investment in finding root cause) or `low` for simple errors (save tokens).

## Example Prompts

**Basic Usage:**
```
"Use gemini to debug this TypeError: 'NoneType' object has no attribute 'split'"
"Get gemini to debug why my API returns 500 errors with the full stack trace: [paste traceback]"
```

## Key Features

- **Generates multiple ranked hypotheses** for systematic debugging
- **Accepts error context**, stack traces, and logs
- **Can reference relevant files** for investigation
- **Supports runtime info** and previous attempts
- **Provides structured root cause analysis** with validation steps
- **Can request additional context** when needed for thorough analysis
- **Image support**: Include error screenshots, stack traces, console output: `"Debug this error using gemini with the stack trace screenshot and the failing test.py"`
- **Web search capability**: When enabled (default: true), identifies when searching for error messages, known issues, or documentation would help solve the problem and recommends specific searches for Claude
- **Large context analysis**: Can analyze extensive log files and multiple related code files simultaneously
- **Multi-language support**: Debug issues across Python, JavaScript, Java, C#, Swift, and more

## Tool Parameters

- `prompt`: Error message, symptoms, or issue description (required)
- `model`: auto|pro|flash|o3|o3-mini|o4-mini|o4-mini-high|gpt4.1 (default: server default)
- `error_context`: Stack trace, logs, or additional error context
- `files`: Files or directories that might be related to the issue (absolute paths)
- `images`: Error screenshots, stack traces, console output (absolute paths)
- `runtime_info`: Environment, versions, or runtime information
- `previous_attempts`: What has been tried already
- `temperature`: Temperature for accuracy (0-1, default 0.2)
- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)
- `use_websearch`: Enable web search for error messages and solutions (default: true)
- `continuation_id`: Continue previous debugging sessions

## Usage Examples

**Basic Error Debugging:**
```
"Debug this TypeError: 'NoneType' object has no attribute 'split' in my parser.py"
```

**With Stack Trace:**
```
"Use gemini to debug why my API returns 500 errors with this stack trace: [paste full traceback]"
```

**With File Context:**
```
"Debug the authentication failure in auth.py and user_model.py with o3"
```

**Performance Debugging:**
```
"Use pro to debug why my application is consuming excessive memory during bulk operations"
```

**With Visual Context:**
```
"Debug this crash using the error screenshot and the related crash_report.log"
```

**Runtime Environment Issues:**
```
"Debug deployment issues with Docker container startup failures, here's the runtime info: [environment details]"
```

## Debugging Methodology

The debug tool follows a systematic approach:

**1. Problem Analysis:**
- Parse error messages and symptoms
- Identify affected components and subsystems
- Understand the expected vs actual behavior

**2. Hypothesis Generation:**
- Generate multiple potential root causes
- Rank hypotheses by likelihood and impact
- Consider both obvious and subtle possibilities

**3. Investigation Strategy:**
- Recommend specific files to examine
- Suggest logging or debugging steps
- Identify missing information needed

**4. Root Cause Analysis:**
- Analyze evidence from code, logs, and context
- Trace execution flow to identify failure points
- Consider environmental and configuration factors

**5. Solution Recommendations:**
- Provide specific fixes with code examples
- Suggest preventive measures
- Recommend testing strategies

## Debugging Categories

**Runtime Errors:**
- Exceptions and crashes
- Null pointer/reference errors
- Type errors and casting issues
- Memory leaks and resource exhaustion

**Logic Errors:**
- Incorrect algorithm implementation
- Off-by-one errors and boundary conditions
- State management issues
- Race conditions and concurrency bugs

**Integration Issues:**
- API communication failures
- Database connection problems
- Third-party service integration
- Configuration and environment issues

**Performance Problems:**
- Slow response times
- Memory usage spikes
- CPU-intensive operations
- I/O bottlenecks

## Best Practices

- **Provide complete error context**: Include full stack traces, error messages, and relevant logs
- **Share relevant code**: Include files mentioned in stack traces or related to the issue
- **Describe expected behavior**: Explain what should happen vs what's actually happening
- **Include environment details**: Runtime versions, configuration, deployment context
- **Mention previous attempts**: What debugging steps have already been tried
- **Use visual context**: Screenshots of error dialogs, console output, or debugging tools
- **Be specific about symptoms**: Describe when, where, and how the issue occurs

## Advanced Features

**Large Log Analysis:**
With models like Gemini Pro (1M context), you can include extensive log files for comprehensive analysis:
```
"Debug application crashes using these large log files: app.log, error.log, system.log"
```

**Multi-File Investigation:**
Analyze multiple related files simultaneously to understand complex issues:
```
"Debug the data processing pipeline issues across processor.py, validator.py, and output_handler.py"
```

**Web Search Integration:**
The tool can recommend specific searches for error messages, known issues, or documentation:
```
After analysis: "Recommended searches for Claude: 'Django 4.2 migration error specific_error_code', 'PostgreSQL connection pool exhaustion solutions'"
```

## When to Use Debug vs Other Tools

- **Use `debug`** for: Specific runtime errors, exceptions, crashes, performance issues
- **Use `codereview`** for: Finding potential bugs in code without specific errors
- **Use `analyze`** for: Understanding code structure and flow without troubleshooting
- **Use `precommit`** for: Validating changes before commit to prevent introducing bugs