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:

Gemini Priority	PR Review Category
high + is_security	🔴 Critical Issues
high	🟡 Important Issues
medium + is_security	🟡 Important Issues
medium	💡 Suggestions
low	💡 Suggestions

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

Indicator	Meaning
⚠️	Pending review (newly integrated from Gemini)
✅	Fixed / Resolved
⏭️	Deferred / Not applicable
🔴	Escalated to blocking

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

Error	Action
No PR found	Inform user, stop
No review comment	Suggest running pr-review-and-document first
No Gemini comments	Inform user, nothing to integrate
API failure	Report error with details
All comments outdated	Inform user, nothing to integrate
All comments already integrated	Inform user, up to date