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 reviewsources.gemini.consumedcommentids; fall back to legacy geminiintegrated_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:**

code here

</details>

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: ``bash METADATAJSON=$(printf '%s\n' "$EXISTINGCONTENT" | ${CLAUDEPLUGINROOT}/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 $METADATAJSON: ``bash # 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.) METADATAFILE=$(mktemp) trap 'rm -f "$METADATA_FILE"' EXIT

# Write the fully-edited metadata JSON to the temp file. printf '%s' "$METADATAJSON" > "$METADATAFILE"

# Replace the metadata block in the comment. UPDATEDCONTENT=$(printf '%s\n' "$EXISTINGCONTENT" | ${CLAUDEPLUGINROOT}/scripts/review-metadata-replace.sh --stdin --metadata-file "$METADATAFILE") `` - Mirror new consumed Gemini comment IDs into BOTH reviewsources.gemini.consumedcommentids AND legacy geminiintegratedids (Phase 2 compatibility window) - Mirror the integration timestamp into BOTH reviewsources.gemini.lastintegratedat AND legacy geminiintegration_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:

``bash # 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. METADATAJSON=$(printf '%s' "$METADATAJSON" | jq \ --argjson newids "$NEWINTEGRATEDIDS" \ --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" ' .reviewsources.gemini.consumedcommentids = ((.reviewsources.gemini.consumedcommentids // []) + $newids | unique) | .reviewsources.gemini.lastintegratedat = $now | .geminiintegratedids = ((.geminiintegratedids // []) + $newids | unique) | .geminiintegrationdate = $now ') ``

$NEWINTEGRATEDIDS must be a JSON array of the integer comment IDs newly consumed in this run (e.g. [2726014213, 2726014217]). - Preserve reviewsources.codex, reviewsources.claude, [Codex] issues, and untagged Claude issues - Increment issue counts in issues object - Update updated_at timestamp

1. Insert new Gemini issues into appropriate sections (Critical, Important, Suggestions)
2. 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

geminiintegratedids and geminiintegrationdate are legacy compatibility fields. Read from reviewsources.gemini.* first, but preserve legacy fields while older skills may still read them. Use ${CLAUDEPLUGINROOT}/scripts/review-metadata-upgrade.sh to normalize old metadata before applying Gemini-specific updates, then ${CLAUDEPLUGIN_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: reviewsources.gemini.consumedcomment_ids grows with each integration
3. New comments only: Only comments not in consumedcommentids 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:**

PR_NUMBER=$(gh pr view --json number -q '.number' || echo "")

</details>

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