Gemini Review Integrator

Gemini Review Integrator

Integrate Gemini Code Assist review suggestions into the pr-review-and-document PR comment.

When to Use

Invoke this skill when:

• A PR has both Gemini Code Assist reviews and a pr-review-and-document comment
• Need to consolidate all review feedback into a single location
• Want to track Gemini suggestions alongside Claude's PR review

Workflow

Step 1: Get PR Number and Verify Prerequisites (Cache-Aware)

PR_NUMBER=$("${CLAUDE_PLUGIN_ROOT}/scripts/get-pr-number.sh")

This uses the branch-to-PR-number cache (branch-map.json) with 1-hour TTL, falling back to GitHub API on cache miss.

If no PR exists, inform the user and stop.

Verify pr-review-and-document comment exists:

${CLAUDE_PLUGIN_ROOT}/scripts/find-review-comment.sh "$PR_NUMBER"

If no review comment exists, inform the user to run pr-review-and-document skill first.

Step 2: Fetch Gemini Code Assist Comments

Fetch all PR review comments (inline code comments):

${CLAUDE_PLUGIN_ROOT}/scripts/fetch-gemini-comments.sh "$PR_NUMBER"

The script returns JSON with Gemini suggestions, including:

• id: Comment ID for deduplication
• priority: high, medium, or low
• is_security: Whether it's a security issue
• is_outdated: Whether the comment is outdated (code changed)
• file: File path
• line: Line number (null if file-level)
• body: Full comment body
• suggestion: Extracted code suggestion (if any)

Step 3: Filter and Deduplicate

Apply filters to Gemini suggestions:

1. Exclude outdated comments: Skip comments where is_outdated: true
2. Check existing integration: Parse metadata for review_sources.gemini.consumed_comment_ids; fall back to legacy gemini_integrated_ids
3. Skip already integrated: Exclude comments whose IDs are already consumed

Step 4: Categorize Suggestions

Map Gemini priorities to pr-review-and-document categories:

Step 5: Format Integrated Suggestions

For each new Gemini suggestion, format as:

<details>
<summary><b>N. ⚠️ [Gemini] Issue Title</b></summary>

**Source:** Gemini Code Assist
**File:** `path/to/file.ts:line`

**Problem:** Description from Gemini comment.

**Suggested Fix:**
```suggestion
code here

Key formatting rules:

• Prefix title with [Gemini] to identify source
• Use ⚠️ status indicator (pending review)
• Include **Source:** Gemini Code Assist line
• Preserve Gemini's suggestion code block if present

Step 6: Update PR Review Comment

1. Fetch existing pr-review-and-document comment body
2. Parse metadata JSON from <!-- pr-review-metadata ... --> block
3. Update metadata:

   • Upgrade metadata to schema 1.1 with the shared helper when needed:

     METADATA_JSON=$(printf '%s\n' "$EXISTING_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh --stdin --last-writer gemini-review-integrator)
     

   • Replace the updated hidden metadata block. Run this after all metadata edits (including the dual-write jq step below) have been applied to $METADATA_JSON:

     # Set up a temp file for the modified metadata JSON.
     # (If this code block already declares its own trap, extend it instead of adding a second line.)
     METADATA_FILE=$(mktemp)
     trap 'rm -f "$METADATA_FILE"' EXIT
     
     # Write the fully-edited metadata JSON to the temp file.
     printf '%s' "$METADATA_JSON" > "$METADATA_FILE"
     
     # Replace the metadata block in the comment.
     UPDATED_CONTENT=$(printf '%s\n' "$EXISTING_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh --stdin --metadata-file "$METADATA_FILE")
     

   • Mirror new consumed Gemini comment IDs into BOTH review_sources.gemini.consumed_comment_ids AND legacy gemini_integrated_ids (Phase 2 compatibility window)

   • Mirror the integration timestamp into BOTH review_sources.gemini.last_integrated_at AND legacy gemini_integration_date

   • Once Phase 2 ships, the legacy fields will be removed in a future release; until then, every write keeps both fields in sync so a Phase-1 reader still sees up-to-date IDs. The shared review-metadata-upgrade.sh helper only preserves existing legacy fields — it never back-fills new IDs — so this skill MUST perform the dual-write itself.

     Apply the dual-write atomically with jq:

     # Dual-write new Gemini IDs + integration timestamp during Phase 2 compat window.
     # Both nested (1.1 canonical) and top-level (1.0 legacy) are kept in sync until
     # the legacy fields are removed in a future release.
     METADATA_JSON=$(printf '%s' "$METADATA_JSON" | jq \
       --argjson new_ids "$NEW_INTEGRATED_IDS" \
       --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '
         .review_sources.gemini.consumed_comment_ids = ((.review_sources.gemini.consumed_comment_ids // []) + $new_ids | unique)
       | .review_sources.gemini.last_integrated_at = $now
       | .gemini_integrated_ids = ((.gemini_integrated_ids // []) + $new_ids | unique)
       | .gemini_integration_date = $now
     ')
     

     $NEW_INTEGRATED_IDS must be a JSON array of the integer comment IDs newly consumed in this run (e.g. [2726014213, 2726014217]).

   • Preserve review_sources.codex, review_sources.claude, [Codex] issues, and untagged Claude issues

   • Increment issue counts in issues object

   • Update updated_at timestamp

4. Insert new Gemini issues into appropriate sections (Critical, Important, Suggestions)
5. Renumber existing issues to accommodate new entries

Pipe updated content to cache-write-comment.sh via --stdin:

EXPECTED_CONTENT_HASH=$(jq -r '.content_hash // ""' ".pr-review-cache/pr-${PR_NUMBER}.json" 2>/dev/null || echo "")

if [ -n "$EXPECTED_CONTENT_HASH" ]; then
  printf '%s\n' "$UPDATED_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER" --expected-content-hash "$EXPECTED_CONTENT_HASH"
else
  printf '%s\n' "$UPDATED_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER"
fi

This updates local cache and syncs to GitHub in one step, without temp files. If the script exits 4, another tool updated the cache; re-read the latest comment, merge only the new Gemini integrations, and retry once.

Step 7: Report Integration Results

Summarize what was integrated:

Gemini Review Integration Complete:
- Found: X Gemini comments
- Outdated (skipped): Y
- Already integrated (skipped): Z
- Newly integrated: W
  - Critical: A
  - Important: B
  - Suggestions: C

Metadata Schema Extension

The pr-review-and-document metadata is extended with schema 1.1 source fields:

{
  "review_sources": {
    "gemini": {
      "consumed_comment_ids": [2726014213, 2726014217],
      "last_integrated_at": "2026-01-26T12:00:00Z"
    }
  },
  "gemini_integrated_ids": [2726014213, 2726014217],
  "gemini_integration_date": "2026-01-26T12:00:00Z"
}

This enables:

• Tracking which Gemini comments have been integrated
• Preventing duplicate integration across multiple runs
• Audit trail for integrated suggestions

gemini_integrated_ids and gemini_integration_date are legacy compatibility fields. Read from review_sources.gemini.* first, but preserve legacy fields while older skills may still read them. Use ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh to normalize old metadata before applying Gemini-specific updates, then ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh to write the updated JSON back without changing unrelated sections.

Gemini Comment Structure

Gemini Code Assist comments have these characteristics:

Priority Indicators (in body):

• ![high](...) - High priority
• ![medium](...) - Medium priority
• ![security-medium](...) or ![security-high](...) - Security-related

Outdated Detection:

• GitHub API field position: null indicates the code has changed
• These comments should be skipped as they may no longer apply

Code Suggestions:

• Enclosed in ````suggestion` blocks
• Should be preserved in integration

Handling Multiple Gemini Review Rounds

Gemini may perform multiple review rounds on a PR. The integration handles this by:

1. ID-based deduplication: Each comment has a unique ID
2. Cumulative tracking: review_sources.gemini.consumed_comment_ids grows with each integration
3. New comments only: Only comments not in consumed_comment_ids are processed

To re-integrate after Gemini runs another review:

1. Run this skill again
2. Only new comments will be added
3. Previously integrated comments remain unchanged

Status Indicators for Gemini Issues

Initial status for all Gemini integrations is ⚠️ (pending review).

Example Integration

Before (pr-review-and-document comment):

### 🟡 Important Issues

<details>
<summary><b>1. ✅ Some Claude-found issue</b></summary>
...
</details>

After integration:

### 🟡 Important Issues

<details>
<summary><b>1. ✅ Some Claude-found issue</b></summary>
...
</details>

<details>
<summary><b>2. ⚠️ [Gemini] Suppress stderr hides errors</b></summary>

**Source:** Gemini Code Assist
**File:** `.claude/skills/pr-review-and-document/scripts/find-review-comment.sh:19`

**Problem:** Suppressing stderr with `2>/dev/null` can hide important underlying errors.

**Suggested Fix:**
```suggestion
  PR_NUMBER=$(gh pr view --json number -q '.number' || echo "")

Validation Checklist

Before completing integration:

• PR number correctly identified
• pr-review-and-document comment exists
• Gemini comments fetched successfully
• Outdated comments filtered out
• Previously integrated comments skipped
• New comments categorized correctly
• Metadata updated with integrated IDs
• Issue counts updated accurately
• Comment posted successfully

Error Handling