Improved docs
This commit is contained in:
Fahad
168
docs/tools/debug.md
Normal file
168
docs/tools/debug.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user