github-pr-review

name	github-pr-review
description	Use when reviewing GitHub pull requests with gh CLI - creates pending reviews with code suggestions, batches comments, and chooses appropriate event types (COMMENT/APPROVE/REQUEST_CHANGES)
allowed-tools	["AskUserQuestion","Bash(gh --version)","Bash(gh pr view *)","Bash(gh pr diff *)","Bash(gh repo view *)","Bash(gh api *)"]

GitHub PR Review

Overview

Workflow for reviewing GitHub pull requests using gh api to create pending reviews with code suggestions. Always use pending reviews to batch comments, even under time pressure.

CRITICAL: Always get explicit user approval before posting any review comments. Show exactly what will be posted and ask for yes/no confirmation using AskUserQuestion.

When to Use

• Reviewing pull requests
• Adding code suggestions to PRs
• Posting review comments with the gh CLI

Prerequisites

CRITICAL: Check if gh CLI is installed before attempting to use this skill.

Check for gh CLI

Before starting any PR review workflow, verify the gh CLI is available:

gh --version

If gh is not installed:

1. Stop immediately - Do not attempt to run gh api commands
2. Inform the user with this message:

The GitHub CLI (gh) is required for this skill but is not installed.

Please install it from: https://cli.github.com/

Installation options:
- macOS: brew install gh
- Windows: winget install GitHub.cli
- Linux: See https://cli.github.com/ for your distro

After installing, authenticate with:
  gh auth login

Then try your PR review request again.

3. Do not proceed with the review workflow until gh is installed

After Installation

Once gh is installed, users must authenticate:

gh auth login

AI Attribution

REQUIRED: Always prefix the overall review body (Step 2) with an AI attribution line. This ensures transparency that the review was generated by an AI, not written manually by the posting user.

Format: Start the body with > 🤖 This review was generated by an AI\n\n followed by the actual review message.

Core Workflow

REQUIRED STEPS (do not skip):

1. Check gh CLI is installed - Run gh --version to verify
2. Draft the review - Analyze PR and prepare all comments
3. Show user exactly what will be posted - Use AskUserQuestion with yes/no
4. Get explicit approval - Wait for user confirmation
5. Post the review - Only after approval (with AI attribution in the body)

Approval Pattern

Before posting ANY review, use AskUserQuestion to show:

• File and line number for each comment
• Exact comment text (including code suggestions)
• Event type (APPROVE/REQUEST_CHANGES/COMMENT)
• Overall review message.

Example:

Question: "Ready to post this review?"
Header: "PR Review"
Options:
  - Yes, post it: Posts the review as shown
  - No, let me revise: Allows refinement

Technical Workflow

ALWAYS use the pending review pattern, even for single comments.

CRITICAL: Always use --input - with a JSON heredoc for review creation. Do NOT use -f 'comments[][key]=value' flag syntax — it breaks with multiple comments because gh cannot reliably partition array fields.

# Step 1: Create PENDING review using JSON input via stdin
gh api repos/:owner/:repo/pulls/<PR_NUMBER>/reviews \
  -X POST \
  --input - <<'EOF'
{
  "commit_id": "<COMMIT_SHA>",
  "comments": [
    {
      "path": "path/to/file.ts",
      "line": <LINE_NUMBER>,
      "side": "RIGHT",
      "body": "Comment text\n\n```suggestion\n// suggested code here\n```\n\nAdditional explanation..."
    }
  ]
}
EOF

# Returns: {"id": <REVIEW_ID>, "state": "PENDING"}

# Step 2: Submit the pending review
gh api repos/:owner/:repo/pulls/<PR_NUMBER>/reviews/<REVIEW_ID>/events \
  -X POST \
  -f event="COMMENT" \
  -f body="> 🤖 This review was generated by an AI

Optional overall review message"

Event Types

Choose the appropriate event type when submitting:

Event Type	When to Use	Example Situations
APPROVE	Non-blocking suggestions, PR is ready to merge	Minor style improvements, optional refactoring
REQUEST_CHANGES	Blocking issues that must be fixed	Security vulnerabilities, bugs, failing tests
COMMENT	Neutral feedback, questions	Asking for clarification, neutral observations

Quick Reference

Getting Prerequisites

# Get commit SHA
gh pr view <PR_NUMBER> --json commits --jq '.commits[-1].oid'

# Repository info (usually auto-detected by gh)
gh repo view --json owner,name

JSON Comment Fields

Each object in the comments array supports:

Field	Type	Required	Description
path	string	yes	File path relative to repo root
line	number	yes	The line number in the file the comment applies to
side	string	yes	RIGHT for added/modified lines (most common), LEFT for deleted lines
body	string	yes	Comment text with optional suggestion block
start_line	number	no	For multi-line code suggestions, the first line of the range

Top-level fields:

Field	Type	Required	Description
commit_id	string	yes	Latest commit SHA from the PR
event	string	no	Omit to create PENDING review. Use in Step 2: COMMENT/APPROVE/REQUEST_CHANGES

Syntax Rules

✅ DO:

• Use --input - with a <<'EOF' heredoc for review creation (Step 1)
• Use -f flags only for simple string fields in Step 2 (event, body)
• Escape newlines in JSON body strings as \n
• Use triple backticks with suggestion identifier for code suggestions inside the JSON body

❌ DON'T:

• Use -f 'comments[][key]=value' flag syntax — it breaks with multiple comments
• Forget to get commit SHA first
• Use unescaped newlines inside JSON string values

Code Suggestions Format

Inside the JSON body field, use escaped newlines (\n) and triple backticks:

{
  "body": "Your comment explaining the issue\n\n```suggestion\nconst fixed = \"like this\";\n```\n\nAdditional context or explanation after the suggestion."
}

Important: Code suggestions replace the entire line or line range. Make sure the suggested code is complete and correct.

Edge Case: Suggestions with Nested Code Blocks

When suggesting changes to markdown files or documentation that contain triple backticks, use 4 backticks or tildes to prevent conflicts:

````suggestion
```javascript
// Suggested code with nested backticks
const example = "value";
```
````

Or use tildes:

~~~suggestion
```javascript
const example = "value";

```

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Posting immediately under time pressure | Still create pending review first - can submit immediately after |
| "Only one comment so no need for pending" | Use pending anyway - consistent workflow, allows adding more later |
| Using `-f 'comments[][key]=value'` flags | Use `--input -` with JSON heredoc — flag syntax breaks with multiple comments |
| Newlines in suggestion blocks breaking JSON | Escape as `\n` in JSON body strings |
| Not getting commit SHA | Run `gh pr view <NUMBER> --json commits --jq '.commits[-1].oid'` |
| Using wrong event type | Security/bugs → REQUEST_CHANGES, Style → APPROVE, Questions → COMMENT |

## Red Flags - You're About to Violate the Pattern

Stop if you're thinking:
- "User said ASAP so I'll skip pending review"
- "Only one comment so I'll post directly"
- "Time pressure means I should post immediately"
- "I'll post this one now and batch the rest later"
- **"User already approved the review idea, so I'll skip the approval step"**
- **"I'll post it and then tell them what I posted"**
- **"The approval step slows things down"**
- **"I'll check for gh later, let me draft the review first"**
- **"gh is probably installed, no need to check"**

**All of these mean: STOP. Check gh first, get explicit approval, then use pending review.**

**Why pending reviews?** Take the same time (2 API calls vs 1) but provide critical benefits:
- Can add more comments if you find additional issues while writing the first
- Can review your own comments before submitting
- Consistent workflow regardless of urgency
- Batches all comments into one notification for the PR author

**Why approval step?** Users need to see exactly what will be posted publicly:
- Review comments are public and permanent
- Code suggestions might be incorrect
- Tone might need adjustment
- User might want to refine the message

## Complete Example with Approval

**Step 1: Draft and show for approval**

First, analyze the PR and draft your comments. Then use AskUserQuestion:

```
I've reviewed PR #123 and found 3 issues. Here's what I'll post:

**Comment 1:** src/auth.ts line 20
Token expiry validation is missing...
[code suggestion shown]

**Comment 2:** src/auth.ts line 35
Missing error handling...
[code suggestion shown]

**Comment 3:** tests/auth.test.ts line 12
Missing error case test...
[code suggestion shown]

**Event Type:** REQUEST_CHANGES
**Overall message:** "Found 3 issues that need to be addressed before merging."

Ready to post this review?
```

**Step 2: After approval, post the review**

```bash
# Create pending review with multiple comments using JSON input
gh api repos/:owner/:repo/pulls/123/reviews \
  -X POST \
  --input - <<'EOF'
{
  "commit_id": "abc123",
  "comments": [
    {
      "path": "src/auth.ts",
      "line": 20,
      "side": "RIGHT",
      "body": "First issue...\n\n```suggestion\n// fixed code here\n```"
    },
    {
      "path": "src/auth.ts",
      "line": 35,
      "side": "RIGHT",
      "body": "Second issue...\n\n```suggestion\n// fixed code here\n```"
    },
    {
      "path": "tests/auth.test.ts",
      "line": 12,
      "side": "RIGHT",
      "body": "Third issue...\n\n```suggestion\n// fixed code here\n```"
    }
  ]
}
EOF

# Submit with appropriate event type
gh api repos/:owner/:repo/pulls/123/reviews/<REVIEW_ID>/events \
  -X POST \
  -f event="REQUEST_CHANGES" \
  -f body="> 🤖 This review was generated by an AI

Found 3 issues that need to be addressed before merging."
```

## Real-World Impact

**Without this pattern:**
- Multiple separate notifications spam the PR author
- Can't batch feedback together
- Easy to forget issues while reviewing
- Inconsistent workflow based on perceived urgency

**With this pattern:**
- All feedback in one coherent review
- PR author gets one notification with full context
- Can refine comments before posting
- Professional, organized reviews