ABOUTME: Skill for invoking Gemini CLI for design reviews and code analysis

ABOUTME: Enforces the Gemini collaboration workflow defined in CLAUDE.md

Gemini Review Skill

Full details: references/workflow.md

Invoke Gemini for collaborative design and code review.

🛑 COMPLETION TRIGGER DETECTION

STOP IMMEDIATELY when you catch yourself saying/thinking:

These phrases are BLOCKING triggers. You MUST NOT proceed until you've verified Gemini review status.

🚨 MANDATORY THRESHOLD CHECK

This is a BLOCKING checkpoint. Execute BEFORE tests/summary/commit:

╔══════════════════════════════════════════════════════════════════╗
║  🛑 STOP - GEMINI REVIEW CHECKPOINT                              ║
║                                                                  ║
║  STEP 1: Count your changes                                      ║
║  Run: git diff --stat | tail -5                                  ║
║                                                                  ║
║  STEP 2: Check thresholds                                        ║
║  □ Modified/created MORE than 3 files with logic changes?        ║
║  □ Wrote MORE than 100 lines of code?                            ║
║  □ Touched security or performance code?                         ║
║                                                                  ║
║  STEP 3: Take action                                             ║
║  ANY YES → CALL GEMINI NOW (before tests, before summary)        ║
║  ALL NO  → Skip Gemini, proceed to tests                         ║
║                                                                  ║
║  ⚠️  DO NOT mark todos complete until this check passes          ║
║  ⚠️  DO NOT run tests until this check passes                    ║
║  ⚠️  DO NOT provide summary until this check passes              ║
╚══════════════════════════════════════════════════════════════════╝

Why this matters: In session 1ea73ffd, Claude modified 8+ files with 300+ lines but skipped Gemini review entirely. This checkpoint prevents that failure mode.

🔄 RESUMED SESSION CHECKPOINT

When a session is resumed from context compaction, STOP and check:

╔══════════════════════════════════════════════════════════════════╗
║  SESSION RESUMED - MANDATORY VERIFICATION                        ║
║                                                                  ║
║  Before continuing ANY work, answer these questions:             ║
║                                                                  ║
║  1. Was I in the middle of implementing code?                    ║
║     → Check the summary for "in progress" or "pending" tasks     ║
║                                                                  ║
║  2. How many files were modified before compaction?              ║
║     → Run: git diff --stat                                       ║
║                                                                  ║
║  3. Did I already call Gemini for review?                        ║
║     → Search summary for "gemini" or "code review"               ║
║                                                                  ║
║  If implementation was in progress AND Gemini wasn't called:     ║
║  → CALL GEMINI FIRST before continuing implementation            ║
║                                                                  ║
║  If implementation is complete but tests weren't run:            ║
║  → Check thresholds (>100 lines OR >3 files) → Call Gemini       ║
╚══════════════════════════════════════════════════════════════════╝

Why this matters: Context compaction loses awareness of the workflow state. The summary may say "continue with X" but omit that Gemini review was pending.

Resume workflow:

1. Session resumes with summary
2. ★ STOP - Read summary carefully ★
3. Check: Was implementation in progress?
4. Check: git diff --stat for change count
5. If thresholds met AND no Gemini review recorded:
   → Call Gemini BEFORE continuing
6. Then proceed with the task

When to Invoke (MANDATORY)

🚨 CRITICAL - Post-Implementation Checkpoint:

• "IMMEDIATELY after implementation" means BEFORE:
  • Running tests
  • Providing summaries to the user
  • Moving to the next task
  • Committing changes
• If you've just finished writing code across multiple files, STOP and call Gemini NOW
• The checkpoint triggers on IMPLEMENTATION COMPLETION, not on commit intent

Self-check phrases that should trigger review:

• "I've implemented..." / "I've added..." / "I've modified..."
• "Let me run the tests" / "Let me commit" ← STOP! Check threshold first!

CRITICAL: After codebase exploration, if you are about to produce recommendations, suggestions, or analysis with actionable items, you MUST call Gemini first. "Proposing solutions" includes architectural reviews that recommend changes.

When to Skip

• <100 lines AND ≤3 files with only mechanical changes
• Mechanical changes: imports, formatting, version bumps
• Documentation-only changes
• String constant propagation

How to Invoke

Command format:

gemini -m gemini-3-pro-preview "Your review prompt here" .

CRITICAL - Model Selection:

• ALWAYS use gemini-3-pro-preview - this is non-negotiable
• Do NOT substitute with other models:
  • ❌ gemini-2.5-pro (older model, less capable)
  • ❌ gemini-2.5-flash (different tier)
  • ❌ gemini-3-flash-preview (different tier)
• If gemini-3-pro-preview fails, report the error to the user rather than silently using a different model

CRITICAL - Execution:

• Always use timeout: 1800000 (30 min) in Bash tool call
• NEVER run as background task; wait for completion synchronously
• Always provide . as final parameter for codebase access

Review Prompts by Type

Design Review (BEFORE implementation)

gemini -m gemini-3-pro-preview "I need to implement [FEATURE]. Help me design the architecture: where should the logic live? What patterns work best for this codebase? Propose alternatives with trade-offs." .

Architecture Review (BEFORE implementation)

gemini -m gemini-3-pro-preview "I'm planning to [CHANGE]. Review the current implementation and propose an optimal strategy. How should it integrate with existing patterns?" .

Architectural Analysis Review (BEFORE presenting findings)

Use this when the user asks for architectural review/analysis and you've explored the codebase:

gemini -m gemini-3-pro-preview "I've explored [COMPONENT] architecture. Before presenting my analysis, review:

Current findings:
- [KEY OBSERVATION 1]
- [KEY OBSERVATION 2]

Questions for counter-analysis:
1. What separation of concerns issues do you see?
2. What patterns should be applied here?
3. Are there alternative architectural approaches I'm missing?
4. What are the trade-offs of the current design?

Provide a counter-analysis to ensure comprehensive review." .

Code Review (AFTER implementation)

gemini -m gemini-3-pro-preview "Review my recent changes for correctness and edge cases. Focus on: [SPECIFIC AREAS]. Check for potential bugs, race conditions, and error handling." .

Security Review (AFTER implementation)

gemini -m gemini-3-pro-preview "Perform a security review of [COMPONENT]. Check for: authentication issues, input validation, token handling, and OWASP top 10 vulnerabilities." .

Performance Review (AFTER implementation)

gemini -m gemini-3-pro-preview "Review the performance optimization I made to [COMPONENT]. Check for: proper async/await usage, memory leaks, and concurrency issues." .

Cross-Service Debug Review (WHEN debugging multi-service issues)

gemini -m gemini-3-pro-preview "Debug cross-service issue: [PROBLEM DESCRIPTION].

Services involved: [LIST SERVICES]
Data flow: [DESCRIBE EXPECTED FLOW]
Observed behavior: [WHAT'S HAPPENING]
Expected behavior: [WHAT SHOULD HAPPEN]

Analyze the data contracts between services and identify where the mismatch occurs. Recommend which service should own the fix." .

Frontend/Backend Alignment Review (WHEN form data doesn't match API)

gemini -m gemini-3-pro-preview "Frontend/Backend alignment issue: [PROBLEM].

Frontend sends: [FIELDS]
Backend expects: [FIELDS]
Database schema: [RELEVANT COLUMNS]

Should the fix be:
A) Frontend explicitly sends the missing field
B) Backend derives the field from other data
C) Both with validation

Analyze both codebases and recommend specific file changes." .

Integration with TDD Workflow

1. User requests feature
2. Claude explores codebase (Explore agent)
3. Claude calls Gemini for design review  ← BEFORE proposing
4. Claude presents options to user
5. User approves approach
6. Claude implements with TDD (Red → Green → Refactor)
7. ★ POST-IMPLEMENTATION CHECKPOINT ★
   If >100 lines OR >3 files:
   Claude calls Gemini for code review  ← IMMEDIATELY (before tests/summary)
8. Claude runs tests
9. Claude provides summary to user
10. Claude commits

The checkpoint at step 7 is BLOCKING - do not proceed to tests or summary until Gemini review is complete.

Integration with Architectural Analysis

1. User requests architectural review/analysis
2. Claude explores codebase (Explore agent, Read, Grep)
3. Claude has initial findings
4. ★ CHECKPOINT: Am I about to produce recommendations? ★
5. Claude calls Gemini for counter-analysis  ← BEFORE presenting
6. Claude combines findings with Gemini's perspective
7. Claude presents comprehensive analysis to user

Model enforcement: MANDATORY gemini-3-pro-preview. Using any other model (gemini-2.5-pro, gemini-2.5-flash, etc.) is a skill violation. Fail loudly, never substitute silently.

Failure Recovery

If Gemini invocation fails:

1. Check the model name is exactly gemini-3-pro-preview (no typos, no substitutions)
2. Verify the . context path is correct
3. Retry with a simpler prompt
4. If model is unavailable: STOP and inform user - do NOT fall back to another model
5. If still failing, document the failure and proceed with explicit note to user

NEVER do this:

# WRONG - silently using different model
gemini -m gemini-2.5-pro "..." .  # ❌ FORBIDDEN

Example Session

User: "Add user authentication to the API"

Claude: "I'll explore the codebase first to understand the current structure."
[Uses Explore agent]

Claude: "Before proposing solutions, let me get Gemini's input on the design."
[Invokes this skill]

gemini -m gemini-3-pro-preview "I need to add user authentication to this API.
Help me design: Should auth be middleware or per-route? JWT vs sessions?
Where should user storage live? Propose alternatives with trade-offs." .

[Gemini responds with recommendations]

Claude: "Based on my exploration and Gemini's recommendations, here are the options..."
[Presents options to user]