290 lines
10 KiB
Markdown
290 lines
10 KiB
Markdown
<!-- Powered by BMAD™ Core -->
|
|
|
|
# Gemini Analysis Task
|
|
|
|
## Purpose
|
|
|
|
This task provides access to Google Gemini CLI's massive context window for analyzing large codebases, big files, or complex multi-file operations that exceed normal context limits. Gemini CLI can handle entire project contexts that would overflow standard AI context windows.
|
|
|
|
## Key Capabilities
|
|
|
|
- **Massive Context Window**: Analyze entire codebases without context limitations
|
|
- **File & Directory Inclusion**: Use `@` syntax for precise file/directory targeting
|
|
- **Multi-File Analysis**: Compare and analyze multiple large files simultaneously
|
|
- **Codebase Flattening**: Alternative to local flattener for large projects
|
|
- **Feature Verification**: Check if specific features are implemented across entire projects
|
|
- **Pattern Discovery**: Find patterns, implementations, and architectural decisions project-wide
|
|
|
|
## When to Use Gemini Analysis
|
|
|
|
### Ideal Use Cases
|
|
|
|
- **Large Codebase Architecture Analysis**: Understanding overall system design
|
|
- **Multi-File Pattern Searching**: Finding implementations across multiple files
|
|
- **Feature Implementation Verification**: Checking if features exist project-wide
|
|
- **Brownfield Project Discovery**: Understanding existing large codebases
|
|
- **Context-Heavy Debugging**: Analyzing complex interactions across many files
|
|
- **Comprehensive Code Reviews**: Reviewing entire feature implementations
|
|
|
|
### Context Size Triggers
|
|
|
|
- Files or directories totaling >100KB of content
|
|
- Analysis requiring >20 files simultaneously
|
|
- Project-wide architectural understanding needed
|
|
- Current context window insufficient for task
|
|
|
|
## Analysis Modes
|
|
|
|
### 1. Single File Analysis
|
|
|
|
**Use Case**: Deep analysis of large individual files
|
|
**Command Pattern**: `gemini "@file/path Analyze this file's structure and purpose"`
|
|
**Examples**:
|
|
|
|
- `@src/main.py Explain this file's architecture and key patterns`
|
|
- `@config/webpack.config.js Break down this configuration and its impact`
|
|
|
|
### 2. Directory Analysis
|
|
|
|
**Use Case**: Understanding structure and patterns within specific directories
|
|
**Command Pattern**: `gemini "@directory/ Analyze the architecture of this codebase section"`
|
|
**Examples**:
|
|
|
|
- `@src/components/ Summarize the component architecture and patterns`
|
|
- `@api/routes/ Document all API endpoints and their purposes`
|
|
|
|
### 3. Multi-Path Analysis
|
|
|
|
**Use Case**: Comparing and analyzing relationships between multiple areas
|
|
**Command Pattern**: `gemini "@path1 @path2 Analyze relationships between these areas"`
|
|
**Examples**:
|
|
|
|
- `@src/ @tests/ Analyze test coverage for the source code`
|
|
- `@frontend/ @backend/ How do these communicate and what are the integration points?`
|
|
|
|
### 4. Project Overview
|
|
|
|
**Use Case**: Comprehensive understanding of entire project
|
|
**Command Pattern**: `gemini --all-files "Provide comprehensive project analysis"`
|
|
**Examples**:
|
|
|
|
- `--all-files "Give me an architectural overview of this entire project"`
|
|
- `--all-files "Summarize the technology stack and key architectural decisions"`
|
|
|
|
### 5. Feature Verification
|
|
|
|
**Use Case**: Checking if specific features or patterns are implemented
|
|
**Command Pattern**: `gemini "@codebase/ Has [feature] been implemented? Show relevant files"`
|
|
**Examples**:
|
|
|
|
- `@src/ @lib/ Has dark mode been implemented? Show relevant files and functions`
|
|
- `@api/ @middleware/ Is rate limiting implemented? Show the implementation details`
|
|
|
|
### 6. Pattern Discovery
|
|
|
|
**Use Case**: Finding specific coding patterns, security measures, or architectural decisions
|
|
**Command Pattern**: `gemini "@codebase/ Find all instances of [pattern] and list with file paths"`
|
|
**Examples**:
|
|
|
|
- `@src/ Are there any React hooks that handle WebSocket connections?`
|
|
- `@backend/ Is proper error handling implemented for all endpoints?`
|
|
|
|
## Task Process
|
|
|
|
### 1. Analysis Request Processing
|
|
|
|
#### Gather Requirements
|
|
|
|
- **Analysis Type**: Which mode fits the user's need?
|
|
- **Target Paths**: What files/directories should be included?
|
|
- **Analysis Depth**: High-level overview vs detailed analysis?
|
|
- **Specific Questions**: What particular aspects to focus on?
|
|
- **Output Format**: How should results be presented?
|
|
|
|
#### Path Validation
|
|
|
|
- **Existence Check**: Verify all specified paths exist
|
|
- **Size Assessment**: Estimate total content size
|
|
- **Permission Validation**: Ensure readable access
|
|
- **Safety Check**: Confirm read-only analysis scope
|
|
|
|
### 2. Command Construction
|
|
|
|
#### Basic Command Structure
|
|
|
|
```bash
|
|
gemini [options] "@path1 @path2 [prompt]"
|
|
```
|
|
|
|
#### Option Selection
|
|
|
|
- **Standard Mode**: `gemini "@path prompt"`
|
|
- **All Files Mode**: `gemini --all-files "prompt"`
|
|
- **Safe Mode**: `gemini --approval-mode default "@path prompt"`
|
|
- **Sandbox Mode**: `gemini --sandbox "@path prompt"` (if editing needed)
|
|
|
|
#### Path Formatting
|
|
|
|
- **Single File**: `@src/main.py`
|
|
- **Directory**: `@src/components/`
|
|
- **Multiple Paths**: `@src/ @tests/ @docs/`
|
|
- **Current Directory**: `@./`
|
|
- **Specific Files**: `@package.json @README.md`
|
|
|
|
### 3. Safety and Validation
|
|
|
|
#### Pre-Execution Checks
|
|
|
|
- **Read-Only Confirmation**: Ensure analysis-only intent
|
|
- **Path Sanitization**: Validate and clean file paths
|
|
- **Size Warnings**: Alert for extremely large contexts
|
|
- **Approval Mode**: Set appropriate safety level
|
|
|
|
#### Command Safety Options
|
|
|
|
```yaml
|
|
safety_levels:
|
|
read_only: 'Default - analysis only, no modifications'
|
|
default: 'Prompt for any file modifications'
|
|
auto_edit: 'Auto-approve edit tools only'
|
|
sandbox: 'Run in safe sandbox environment'
|
|
```
|
|
|
|
### 4. Execution and Results
|
|
|
|
#### Command Execution
|
|
|
|
1. **Validate Paths**: Confirm all targets exist and are accessible
|
|
2. **Construct Command**: Build proper Gemini CLI command
|
|
3. **Execute Analysis**: Run Gemini CLI with specified parameters
|
|
4. **Capture Output**: Collect and format analysis results
|
|
5. **Error Handling**: Manage CLI failures or timeouts
|
|
|
|
#### Result Processing
|
|
|
|
- **Output Formatting**: Structure results for readability
|
|
- **Key Insights Extraction**: Highlight critical findings
|
|
- **Follow-up Suggestions**: Recommend next steps
|
|
- **Source Documentation**: Reference analyzed files/paths
|
|
|
|
### 5. Integration with BMAD Workflow
|
|
|
|
#### Result Documentation
|
|
|
|
- **Store in Project**: Save significant analyses in `docs/analysis/`
|
|
- **Reference in Stories**: Link analyses to relevant development stories
|
|
- **Architecture Updates**: Update architecture docs with findings
|
|
- **Knowledge Preservation**: Maintain analysis artifacts for team reference
|
|
|
|
#### Follow-Up Actions
|
|
|
|
- **Story Creation**: Generate development stories from findings
|
|
- **Architecture Review**: Update architectural documentation
|
|
- **Technical Debt**: Identify and document technical debt items
|
|
- **Research Coordination**: Trigger detailed research if needed
|
|
|
|
## Command Templates
|
|
|
|
### Architecture Analysis
|
|
|
|
```bash
|
|
# Overall project architecture
|
|
gemini --all-files "Analyze the overall architecture of this project. Include technology stack, key patterns, and architectural decisions."
|
|
|
|
# Specific component architecture
|
|
gemini "@src/components/ Analyze the component architecture. What patterns are used and how are components organized?"
|
|
|
|
# Backend architecture
|
|
gemini "@api/ @services/ @middleware/ Analyze the backend architecture. How are routes organized and what patterns are used?"
|
|
```
|
|
|
|
### Feature Verification
|
|
|
|
```bash
|
|
# Authentication implementation
|
|
gemini "@src/ @api/ Is JWT authentication fully implemented? Show all auth-related files and middleware."
|
|
|
|
# Security measures
|
|
gemini "@src/ @api/ What security measures are implemented? Look for input validation, CORS, rate limiting."
|
|
|
|
# Testing coverage
|
|
gemini "@src/ @tests/ Analyze test coverage. Which areas are well-tested and which need more tests?"
|
|
```
|
|
|
|
### Code Quality Analysis
|
|
|
|
```bash
|
|
# Error handling patterns
|
|
gemini "@src/ @api/ How is error handling implemented throughout the codebase? Show examples."
|
|
|
|
# Performance considerations
|
|
gemini "@src/ @lib/ What performance optimizations are in place? Identify potential bottlenecks."
|
|
|
|
# Code organization
|
|
gemini "@src/ How is the code organized? What are the main modules and their responsibilities?"
|
|
```
|
|
|
|
### Technology Assessment
|
|
|
|
```bash
|
|
# Dependency analysis
|
|
gemini "@package.json @src/ What are the key dependencies and how are they used in the code?"
|
|
|
|
# Build system analysis
|
|
gemini "@webpack.config.js @package.json @src/ How is the build system configured and what optimizations are in place?"
|
|
|
|
# Database integration
|
|
gemini "@models/ @migrations/ @src/ How is the database integrated? What ORM patterns are used?"
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
### Common Issues
|
|
|
|
- **Path Not Found**: Specified files/directories don't exist
|
|
- **Context Too Large**: Even Gemini's context has limits
|
|
- **CLI Unavailable**: Gemini CLI not installed or configured
|
|
- **Permission Denied**: Cannot read specified files
|
|
- **Command Timeout**: Analysis takes too long to complete
|
|
|
|
### Error Recovery
|
|
|
|
- **Path Validation**: Pre-validate all paths before execution
|
|
- **Graceful Degradation**: Suggest smaller scope if context too large
|
|
- **Alternative Approaches**: Offer local flattener or partial analysis
|
|
- **Clear Error Messages**: Provide actionable error information
|
|
- **Fallback Options**: Suggest manual analysis approaches
|
|
|
|
### Safety Measures
|
|
|
|
- **Read-Only Default**: Never modify files without explicit permission
|
|
- **Approval Prompts**: Confirm any file modifications
|
|
- **Sandbox Options**: Use sandbox mode for risky operations
|
|
- **Timeout Protection**: Prevent hanging operations
|
|
- **Resource Monitoring**: Track memory and processing usage
|
|
|
|
## Integration Notes
|
|
|
|
### With Existing BMAD Tools
|
|
|
|
- **Flattener Integration**: Use existing flattener for preprocessing when needed
|
|
- **Research Coordination**: Can trigger research system for follow-up analysis
|
|
- **Story Generation**: Results can inform story creation
|
|
- **Architecture Documentation**: Updates architectural understanding
|
|
|
|
### With Core Configuration
|
|
|
|
- **Command Templates**: Stored in core-config.yaml for consistency
|
|
- **Default Settings**: Safety and approval modes configured globally
|
|
- **Path Patterns**: Common path combinations for different project types
|
|
- **Integration Points**: How Gemini analysis feeds into BMAD workflow
|
|
|
|
### Agent Accessibility
|
|
|
|
All agents with Gemini analysis capability will have access to:
|
|
|
|
- **Standard Analysis**: `*gemini-analyze` command for common patterns
|
|
- **Custom Queries**: Ability to specify custom analysis prompts
|
|
- **Result Integration**: Automatic integration with agent workflows
|
|
- **Safety Controls**: Appropriate safety measures for agent context
|