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:

Exclude outdated comments: Skip comments where is_outdated: true
Check existing integration: Parse metadata for review_sources.gemini.consumed_comment_ids; fall back to legacy gemini_integrated_ids
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

Fetch existing pr-review-and-document comment body
Parse metadata JSON from  block

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

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

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

To re-integrate after Gemini runs another review:

Run this skill again
Only new comments will be added
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