pr-review-loop

Original source / Raw SKILL.md

---
name: pr-review-loop
description: Manage PR review feedback loops with Gemini Code Assist. Use when pushing changes to a PR, iterating on review feedback, or monitoring CI/review status. Automatically falls back to Claude when Gemini is rate-limited.
license: MIT
environment: claude-code
---

# PR Review Loop

Streamline the push-review-fix cycle for PRs with automated reviewers like Gemini Code Assist.

## CRITICAL: Git Command Restrictions

**YOU DO NOT HAVE PERMISSION TO USE RAW GIT COMMANDS.**

| Forbidden | Use Instead |
|-----------|-------------|
| `git commit` | `commit-and-push.sh "msg"` |
| `git push` | `commit-and-push.sh "msg"` |

All scripts are in `~/.claude/skills/pr-review-loop/scripts/`.

## When to Use

Invoke when user:
- Pushes changes and waits for CI/reviews
- Says "new reviews available" or "check PR feedback"
- Iterates on review feedback from Gemini or other reviewers
- Wants to monitor PR status
- Asks to address reviewer comments

## Core Workflow

```
1. Get unresolved comments (--wait to poll 5 min)
2. For EACH comment: fix OR skip, then REPLY
3. Commit using commit-and-push.sh (NEVER raw git)
4. Trigger next review with trigger-review.sh --wait
5. Repeat until no new issues
6. One final loop, then ask about merge
```

### Step-by-step Commands

**1. Check for comments:**
```bash
~/.claude/skills/pr-review-loop/scripts/summarize-reviews.sh <PR>
~/.claude/skills/pr-review-loop/scripts/get-review-comments.sh <PR> --with-ids --wait
```

**2. Reply to EVERY comment:**
```bash
~/.claude/skills/pr-review-loop/scripts/reply-to-comment.sh <PR> <id> "Fixed - description"
~/.claude/skills/pr-review-loop/scripts/reply-to-comment.sh <PR> <id> "Won't fix - reason"
```

**3. Commit and push:**
```bash
~/.claude/skills/pr-review-loop/scripts/commit-and-push.sh "fix: description"
```

**4. Trigger next review:**
```bash
~/.claude/skills/pr-review-loop/scripts/trigger-review.sh <PR> --wait
```

## Be Skeptical of Reviews

**Not all suggestions are good.** Evaluate critically:

- Does this improve the code, or is it pedantic?
- Is this appropriate for the project context?
- Would this add unnecessary complexity?

**Skip suggestions that are:**
- Platform-specific when not applicable
- Overly defensive (excessive null checks)
- Stylistic preferences not matching project
- Documentation for self-explanatory code

When in doubt, ask the user.

## One More Loop Rule

When all comments are resolved:
1. Track in TodoWrite: "Final verification loop"
2. Trigger one more review cycle
3. If no actionable feedback → ask about merge
4. If new fixes needed → remove todo, do fresh "one more" after

## Gemini Rate Limit Fallback

When Gemini hits daily quota, use Claude:

```bash
~/.claude/skills/pr-review-loop/scripts/trigger-review.sh <PR> --claude
# OR
~/.claude/skills/pr-review-loop/scripts/claude-review.sh <PR>
```

Then use Task tool with the generated prompt.

## Scripts Quick Reference

| Script | Purpose |
|--------|---------|
| `commit-and-push.sh "msg"` | **ALWAYS USE** for commits |
| `reply-to-comment.sh <PR> <id> "msg"` | Reply and auto-resolve |
| `get-review-comments.sh <PR> --with-ids --wait` | Fetch comments |
| `trigger-review.sh <PR> --wait` | Trigger review cycle |
| `summarize-reviews.sh <PR>` | Summary by priority/file |
| `claude-review.sh <PR>` | Claude fallback prompt |

See `references/scripts-reference.md` for complete documentation.

## Reply Templates

- **Fixed:** "Fixed - [description]"
- **Won't fix:** "Won't fix - [reason]"
- **Deferred:** "Good catch, tracking in #issue"
- **Acknowledged:** "Acknowledged - [explanation]"

## Prerequisites

- `gh` CLI authenticated
- `pre-commit` installed (`pip install pre-commit`)
- Pre-commit hooks in repo (`.pre-commit-config.yaml`)

## Permission Setup

Add to `.claude/settings.local.json`:

```
Bash(~/.claude/skills/pr-review-loop/scripts/commit-and-push.sh:*)
Bash(~/.claude/skills/pr-review-loop/scripts/reply-to-comment.sh:*)
Bash(~/.claude/skills/pr-review-loop/scripts/trigger-review.sh:*)
```

## References

- `references/scripts-reference.md` - Complete script documentation
- `references/workflow-examples.md` - End-to-end examples


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/scripts-reference.md

```markdown
# Scripts Reference

Complete reference for all PR Review Loop scripts.

## Core Scripts

### commit-and-push.sh

**CRITICAL: ALWAYS use this instead of raw `git commit` or `git push`.**

```bash
~/.claude/skills/pr-review-loop/scripts/commit-and-push.sh "fix: description"
~/.claude/skills/pr-review-loop/scripts/commit-and-push.sh "fix: description" --trigger-review
```

**What it does:**
1. Runs pre-commit hooks if available
2. Stages all changes (`git add -A`)
3. Commits with proper footer (Claude Code attribution)
4. Pushes to origin
5. Optionally triggers a new review

**Flags:**
- `--trigger-review`: Also trigger Gemini review after push

---

### reply-to-comment.sh

**CRITICAL: ALWAYS reply to every comment using this script.**

```bash
~/.claude/skills/pr-review-loop/scripts/reply-to-comment.sh <PR> <comment-id> "Fixed - description"
~/.claude/skills/pr-review-loop/scripts/reply-to-comment.sh <PR> <comment-id> "Won't fix - reason"
~/.claude/skills/pr-review-loop/scripts/reply-to-comment.sh <PR> <comment-id> "Acknowledged" --no-resolve
```

**What it does:**
1. Posts reply to the specified comment
2. Automatically resolves the thread (unless `--no-resolve`)
3. Uses GitHub GraphQL API to find and resolve thread

**Parameters:**
- `<PR>`: PR number (e.g., `42`)
- `<comment-id>`: Numeric comment ID from `get-review-comments.sh --with-ids`
- `"message"`: Reply text

**Flags:**
- `--no-resolve`: Post reply without resolving the thread

---

### get-review-comments.sh

Fetch review comments with optional filtering and polling.

```bash
~/.claude/skills/pr-review-loop/scripts/get-review-comments.sh <PR>
~/.claude/skills/pr-review-loop/scripts/get-review-comments.sh <PR> --with-ids
~/.claude/skills/pr-review-loop/scripts/get-review-comments.sh <PR> --with-ids --wait
~/.claude/skills/pr-review-loop/scripts/get-review-comments.sh <PR> --all
~/.claude/skills/pr-review-loop/scripts/get-review-comments.sh <PR> --latest
```

**Flags:**
- `--with-ids`: Include comment IDs for replying (use this!)
- `--wait`: Poll every 30s for up to 5 minutes waiting for comments
- `--all`: Include resolved threads (default: unresolved only)
- `--latest`: Only comments on latest commit

**Output format (with --with-ids):**
```
=== Comment ID: 12345 | Node ID: PRR_xxx ===
File: src/auth.py:42
Priority: high

[Comment body with suggestion]

---
```

---

### trigger-review.sh

Trigger a code review (Gemini or Claude fallback).

```bash
~/.claude/skills/pr-review-loop/scripts/trigger-review.sh <PR>
~/.claude/skills/pr-review-loop/scripts/trigger-review.sh <PR> --wait
~/.claude/skills/pr-review-loop/scripts/trigger-review.sh <PR> --claude
~/.claude/skills/pr-review-loop/scripts/trigger-review.sh --wait  # Auto-detect PR
```

**Flags:**
- `--wait`: Poll for up to 5 minutes until comments appear
- `--claude`: Skip Gemini, use Claude agent directly

**Behavior:**
1. Checks if Gemini is rate-limited first
2. If rate-limited, shows fallback instructions
3. Otherwise, posts `/gemini review` comment
4. If `--wait`, polls until comments appear

---

### summarize-reviews.sh

Summary of review comments by priority and file.

```bash
~/.claude/skills/pr-review-loop/scripts/summarize-reviews.sh <PR>
~/.claude/skills/pr-review-loop/scripts/summarize-reviews.sh <PR> --all
```

**Output:**
```
=== PR #42 Review Summary ===

## By Priority
- high: 2 comments
- medium: 5 comments
- low: 1 comments

## By File
- src/auth.py: 4 comments
- src/utils.py: 3 comments
- tests/test_auth.py: 1 comments

## High Priority Items
- [src/auth.py:42] Security: Token not validated properly
- [src/auth.py:78] Security: Missing rate limiting
```

---

## Support Scripts

### claude-review.sh

Generate Claude agent prompt for code review (Gemini fallback).

```bash
~/.claude/skills/pr-review-loop/scripts/claude-review.sh <PR>
```

**Output:**
- Displays structured prompt for Task tool
- Saves prompt to `/tmp/claude_review_prompt_<PR>.txt`

**Use with Task tool:**
```
Task tool:
  subagent_type: general-purpose
  description: Review PR #<PR>
  prompt: (contents of /tmp/claude_review_prompt_<PR>.txt)
```

---

### check-gemini-quota.sh

Check if Gemini Code Assist is rate-limited.

```bash
~/.claude/skills/pr-review-loop/scripts/check-gemini-quota.sh <PR>
```

**Exit codes:**
- `0`: Gemini available
- `1`: Gemini rate-limited

**Output (JSON):**
```json
{"status": "available", "reason": "no quota warning in last comment"}
```
or
```json
{"status": "rate-limited", "reason": "quota exceeded", "detected_at": "2025-12-14T..."}
```

---

### watch-pr.sh

Background monitor for CI checks and review comments.

```bash
~/.claude/skills/pr-review-loop/scripts/watch-pr.sh <PR>
```

**Behavior:**
- Polls every 30 seconds
- Reports CI status changes
- Detects new reviews/comments
- Alerts on Gemini quota exceeded
- Designed for background execution

---

### resolve-comment.sh

Manually resolve (minimize/hide) a comment thread.

```bash
~/.claude/skills/pr-review-loop/scripts/resolve-comment.sh <node-id> [reason]
```

**Parameters:**
- `<node-id>`: GraphQL node ID (from `get-review-comments.sh --with-ids`)
- `[reason]`: RESOLVED (default), OUTDATED, OFF_TOPIC, ABUSE, SPAM

**Note:** Prefer `reply-to-comment.sh` which auto-resolves.

```

### references/workflow-examples.md

```markdown
# Workflow Examples

Complete examples of PR Review Loop workflows.

## Example 1: Fresh PR Review Cycle

**Scenario:** Just pushed a PR and want to address reviewer feedback.

```bash
# 1. Get summary of unresolved comments
~/.claude/skills/pr-review-loop/scripts/summarize-reviews.sh 42

# 2. Get detailed comments with IDs (wait for Gemini if just pushed)
~/.claude/skills/pr-review-loop/scripts/get-review-comments.sh 42 --with-ids --wait

# 3. For each comment:
#    - Read the suggestion
#    - Apply fix OR decide to skip
#    - Reply to the comment (auto-resolves)
~/.claude/skills/pr-review-loop/scripts/reply-to-comment.sh 42 12345 "Fixed - added input validation"
~/.claude/skills/pr-review-loop/scripts/reply-to-comment.sh 42 12346 "Won't fix - this is intentional for backwards compat"

# 4. Commit and push (NEVER use raw git)
~/.claude/skills/pr-review-loop/scripts/commit-and-push.sh "fix: address review feedback"

# 5. Trigger next review and wait
~/.claude/skills/pr-review-loop/scripts/trigger-review.sh 42 --wait

# 6. Repeat from step 1
```

---

## Example 2: Gemini Rate Limited - Claude Fallback

**Scenario:** Gemini hit daily quota, need code review.

```bash
# 1. Check quota status
~/.claude/skills/pr-review-loop/scripts/check-gemini-quota.sh 42
# Output: {"status": "rate-limited", "reason": "quota exceeded", ...}

# 2. Generate Claude review prompt
~/.claude/skills/pr-review-loop/scripts/claude-review.sh 42

# 3. Use Task tool with the generated prompt
# Task tool:
#   subagent_type: general-purpose
#   description: Review PR #42
#   prompt: (contents of /tmp/claude_review_prompt_42.txt)

# 4. After Claude posts review, continue normal workflow
~/.claude/skills/pr-review-loop/scripts/get-review-comments.sh 42 --with-ids
```

---

## Example 3: Final Verification Loop

**Scenario:** All comments resolved, doing final check.

```bash
# 1. Verify no unresolved comments
~/.claude/skills/pr-review-loop/scripts/get-review-comments.sh 42 --with-ids
# Output: No unresolved review comments.

# 2. Track in TodoWrite that we're in final verification
# Todo: "Final verification loop - if no actionable feedback, ready to merge"

# 3. Trigger one more review
~/.claude/skills/pr-review-loop/scripts/trigger-review.sh 42 --wait

# 4. Check for new comments
~/.claude/skills/pr-review-loop/scripts/get-review-comments.sh 42 --with-ids

# 5. If no new actionable feedback:
#    "We've completed the review cycles. Ready to merge, or want to address more?"

# 5b. If new feedback that requires fixes:
#     - Remove "final verification loop" todo
#     - Fix issues, reply, push
#     - Do another "one more loop" after
```

---

## Example 4: Skip Pedantic Suggestions

**Scenario:** Reviewer suggesting unnecessary changes.

```bash
# Comment: "Consider adding null check for this parameter"
# (Internal function, caller always passes valid data)

# Reply explaining why we're skipping
~/.claude/skills/pr-review-loop/scripts/reply-to-comment.sh 42 12347 \
  "Won't fix - this is an internal helper, caller guarantees valid input. Adding null checks would add noise without benefit."
```

**Guidelines for skipping:**
- Platform-specific when not applicable
- Overly defensive (excessive null checks, unlikely edge cases)
- Stylistic preferences not matching project conventions
- Documentation for self-explanatory code

---

## Example 5: Background Monitoring

**Scenario:** Long-running PR, want to monitor in background.

```bash
# Start background monitor
~/.claude/skills/pr-review-loop/scripts/watch-pr.sh 42 &

# Output example:
# === Watching PR #42 ===
# Started at: Sat Dec 14 13:45:00 MST 2025
#
# Initial state: 2 reviews, 5 inline comments, 3 PR comments
#
# --- CI Status (13:45:30) ---
# ✓ lint (1m 23s)
# ✓ test (2m 45s)
# * deploy-preview (running)
#
# !!! NEW REVIEW COMMENTS DETECTED !!!
# Comments: 5 -> 8
```

---

## Reply Templates

Standard templates for common responses:

| Situation | Template |
|-----------|----------|
| Fixed issue | `"Fixed - [description of change]"` |
| Won't fix (valid reason) | `"Won't fix - [reason: intentional, out of scope, etc.]"` |
| Deferred to issue | `"Good catch, tracking in #[issue-number]"` |
| Acknowledged info | `"Acknowledged - [explanation of understanding]"` |
| Needs discussion | `"Let's discuss - [question or concern]"` |
| Already addressed | `"Already addressed in [commit/file]"` |

---

## Critical Rules Checklist

Before each cycle, verify:

- [ ] Using `commit-and-push.sh` (never raw git)
- [ ] Replying to EVERY comment (never leave unreplied)
- [ ] Using `--wait` flag when polling for comments
- [ ] Evaluating suggestions critically (not blindly applying)
- [ ] Tracking if in "final verification loop"

---

## Diminishing Returns Signals

After 2-3 cycles, watch for:

- Same type of issue flagged repeatedly
- Comments about minor style preferences
- Fewer comments per cycle
- Lower priority issues (medium → low)
- Nitpicks rather than substantive feedback

When these appear, consider doing final verification loop.

```