gemini-consult

What this skill does

# Gemini Consult: Large Codebase Analysis Assistant

Intelligent consultation orchestrator that leverages Google Gemini's CLI for analyzing codebases exceeding typical context limitations.

## Core Purpose

Bridge the gap between context-constrained AI assistants and comprehensive codebase understanding by orchestrating strategic use of Google Gemini's expanded context window.

**Problem it solves:**
- Claude Code's context limits prevent full codebase analysis
- Large file comparisons exceed token budgets
- Project-wide pattern detection requires more context than available
- Architectural decisions need holistic codebase visibility

**Solution approach:**
- Intelligently route appropriate queries to Gemini CLI
- Construct optimal @ syntax queries for maximum insight
- Synthesize Gemini's analysis back into Claude Code workflow
- Preserve session efficiency by avoiding unnecessary context consumption

## When to Use Gemini Consult

**Trigger Conditions (Auto-recommend):**

The skill should activate when:
- User asks about "entire codebase", "whole project", "all files"
- Analysis scope > 5 files or > 100KB combined content
- Comparative analysis needed across distant modules
- Architecture or pattern questions requiring project-wide view
- Security audit or compliance verification across codebase
- Feature implementation verification in large projects

**User Explicit Triggers:**
- "Use Gemini to analyze..."
- "Consult Gemini about..."
- "@gemini check if..."

**When NOT to use:**
- Single file analysis (< 50KB) → Use Claude Code Read tool
- Already have sufficient context loaded
- Real-time debugging or rapid iteration
- Questions answerable from loaded files

## The 3-Phase Consultation Workflow

### Phase 1: Query Assessment & Planning

**Objective:** Determine if Gemini consultation is appropriate and construct optimal query strategy.

**Assessment Checklist:**
```javascript
assessment = {
  scope_size: estimate_file_count_and_size(),
  analysis_type: identify_analysis_category(),
  context_available: check_current_session_context(),
  query_complexity: evaluate_question_depth()
}

recommendation = {
  use_gemini: scope_size > threshold || analysis_type in ['architecture', 'security_audit', 'cross_project'],
  query_strategy: construct_query_plan(),
  expected_value: estimate_insight_gain()
}
```

**User Interaction:**

Present recommendation clearly:

"This analysis requires examining **[N files / X MB]** across **[scope]**. I recommend using Gemini CLI because [reason].

I'll construct a query that:
- Includes: [file patterns]
- Focuses on: [specific analysis aspects]
- Returns: [expected insights]

Proceed with Gemini consultation? [Yes / Adjust scope / Use Claude Code only]"

**Query Construction Strategy:**

Based on analysis type, determine optimal @ syntax pattern:

1. **Full Project Analysis:**
   ```bash
   gemini --all_files -p "Analyze complete project architecture"
   ```

2. **Directory-Scoped Analysis:**
   ```bash
   gemini -p "@src/ @tests/ Compare implementation vs test coverage"
   ```

3. **Multi-File Comparison:**
   ```bash
   gemini -p "@src/auth/login.js @src/auth/register.js @src/middleware/auth.js Analyze authentication flow consistency"
   ```

4. **Targeted Pattern Search:**
   ```bash
   gemini -p "@src/**/*.js Find all error handling patterns and identify inconsistencies"
   ```

### Phase 2: Query Execution & Monitoring

**Objective:** Execute Gemini CLI query and capture comprehensive output.

**Execution Protocol:**

1. **Construct Command:**
   ```bash
   gemini_command = build_query(
     scope: assessment.scope,
     prompt: refined_user_question,
     flags: determine_flags()
   )
   ```

2. **Execute with Monitoring:**
   ```bash
   # Execute via Bash tool
   result = bash_execute(gemini_command, timeout=120)

   # Monitor for:
   # - CLI availability (is gemini installed?)
   # - Authentication status (logged in?)
   # - Rate limiting (hit quota?)
   # - Error messages
   ```

3. **Capture Output:**
   - Full response text
   - Any warnings or errors
   - File inclusion confirmations
   - Token usage statistics (if available)

**Error Handling:**

```javascript
if (error.type === 'CLI_NOT_FOUND') {
  return {
    status: 'blocked',
    message: "Gemini CLI not installed. Install: npm install -g @google/generative-ai",
    fallback: "Use Claude Code tools for subset analysis?"
  }
}

if (error.type === 'AUTH_REQUIRED') {
  return {
    status: 'blocked',
    message: "Gemini CLI requires authentication. Run: gemini auth login",
    fallback: null
  }
}

if (error.type === 'RATE_LIMIT') {
  return {
    status: 'retry',
    message: "Gemini API rate limit reached. Retry in [time] or reduce scope?",
    fallback: "Split analysis into smaller chunks?"
  }
}

if (error.type === 'CONTEXT_OVERFLOW') {
  return {
    status: 'adjust',
    message: "Even Gemini's context exceeded. Analysis scope too large.",
    strategy: "Split into multiple focused queries with specific file patterns"
  }
}
```

### Phase 3: Synthesis & Integration

**Objective:** Transform Gemini's output into actionable insights for Claude Code workflow.

**Synthesis Process:**

1. **Parse Gemini Response:**
   - Extract key findings
   - Identify file-specific insights (with line references)
   - Categorize recommendations
   - Note confidence levels or uncertainties

2. **Contextualize for Current Session:**
   ```markdown
   ## Gemini Consultation Results

   **Query:** [original question]
   **Scope:** [files/directories analyzed]
   **Key Findings:**

   1. [Finding with file:line references]
   2. [Finding with architectural implications]
   3. [Finding with security considerations]

   **Recommendations:**
   - [Actionable item 1]
   - [Actionable item 2]

   **Follow-up Actions:**
   - [ ] Review identified files in Claude Code
   - [ ] Implement suggested changes
   - [ ] Verify with local testing
   ```

3. **Store in Cipher (Memory):**
   ```
   cipher_store("Gemini Consultation - [Topic]

   Analysis Type: [architecture/security/feature/pattern]
   Scope: [file patterns]
   Date: [timestamp]

   Key Insights:
   - [Insight 1 with file references]
   - [Insight 2 with implications]

   Recommended Actions:
   - [Action 1]
   - [Action 2]

   Query Pattern Used:
   ```bash
   [gemini command]
   ```

   Results archived for future reference.")
   ```

4. **Present to User:**

   Clear, structured output:

   "✅ Gemini Analysis Complete

   **Analyzed:** [N files across M directories]

   **Critical Findings:**

   1. **[Category]:** [Finding]
      - Files: `src/file1.js:45`, `src/file2.js:89`
      - Impact: [High/Medium/Low]
      - Action: [Specific recommendation]

   2. **[Category]:** [Finding]
      ...

   **Next Steps:**

   I've stored these insights in Cipher for future reference. Would you like me to:

   A) Deep dive into specific finding [#1, #2, etc.]
   B) Implement recommended changes
   C) Run focused analysis on subset
   D) Continue with different question"

## Analysis Type Patterns

### Architecture Analysis

**Trigger Patterns:**
- "How is [system] architected?"
- "What's the overall structure?"
- "Explain the codebase organization"

**Query Construction:**
```bash
gemini --all_files -p "Analyze the complete architecture:
1. Identify main components and their responsibilities
2. Map data flow between modules
3. Describe architectural patterns used
4. Note any architectural inconsistencies
5. Highlight coupling and dependency issues"
```

**Synthesis Focus:**
- Component diagram (textual representation)
- Dependency graph insights
- Pattern identification
- Architectural recommendations

### Security Audit

**Trigger Patterns:**
- "Security vulnerabilities?"
- "Check for [security issue]"
- "Audit authentication/authorization"

**Query Construction:**
```bash
gemini -p "@src/ @lib/ Perform security audit:
1. Identify potential SQL injection points
2. Check for XSS vulnerabilities
3. Verify authentication implemen