BMAD-METHOD/bmad-core/tasks/gemini-analysis.md

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

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

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

# 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

# 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

# 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

# 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