description: Review and approve/merge pull requests as a maintainer (full workflow with approve, request changes, merge, close actions)

Pull Request Review Command

Use this when: You're reviewing someone's pull request as a maintainer and need to approve, request changes, merge, or close it.

Performs comprehensive review with code quality and metadata checks, then provides an interactive workflow for approval actions. Automatically detects contributor type (internal/external/bot) and adapts communication tone (warm/welcoming for external, professional for internal, technical/professional for bots).

Usage

/pr-review <PR_NUMBER>

Reviews any pull request and presents action choices for approval, changes, or closure.

Required: PR number

Works with: All PRs (internal, external, and bots)

Special handling: Automatically detects contributor type and adapts messaging (warm for external, professional for internal, technical for bots). Default "Approve and merge" for pulumi-bot metadata PRs.

Process

CRITICAL SUCCESS CRITERIA: Complete all 10 steps in sequence. Every step is mandatory and serves a critical purpose in the review workflow. DO NOT SKIP ANY STEP OR END THE WORKFLOW PREMATURELY!

Step Counter: Display progress before each step as: [Step X/10] followed by the step heading. This helps users track progress through the workflow.

References: Always follow the detailed instructions in the referenced documents for each step. The references contain the complete implementation details required.

Step 1: Verify PR and Detect Contributor Type

Run the contributor detection script:
```
bash .claude/commands/pr-review/scripts/contributor-detection.sh {{arg}}
```
The script outputs:
- AUTHOR - GitHub username
- CONTRIBUTOR_TYPE - bot/internal/external
- PR_METADATA - JSON with number, title, url
- FILES_CHANGED - List of changed file paths
- PR_DATA_JSON - Complete PR data for caching
After running the script, store the following for later steps:
- PR data (in PR_DATA variable for use in later steps)
- Contributor type (bot/internal/external)
- File paths (displayed for Step 4 reference)
Critical! Display this output to the user immediately:
```
## Contributor Detection

[icon] Reviewing PR #{{arg}} from @username ([type] contributor)
```
Icons:
- 🤖 for bot account
- 📝 for internal contributors
- 🌍 for external contributors

Continue to Step 2.

Step 2: Gather PR Diff

View the full PR context: gh pr view {{arg}}
Get the diff: gh pr diff {{arg}}
Note the PR title, description, files changed, additions/deletions, and labels

Continue to Step 3.

Step 3: Present Test Deployment and Review Guidance

CRITICAL: This step must be completed and presented to the user IMMEDIATELY after Step 2 and BEFORE starting Step 4. Do not delay this output.

Run the test deployment guidance script:
```
bash .claude/commands/pr-review/scripts/test-deployment-guidance.sh {{arg}}
```
The script outputs JSON with:
- prNumber - The pull request number
- deploymentUrl - The preview deployment URL or null
- deploymentStatus - "ready" or "pending"
- isAutomationPR - Whether the PR was opened by an automation bot
- fileCategories - Categorized changed files
Parse the JSON output and analyze the PR diff context to understand what changed.
Critical! Present deployment review with context-aware guidance to the user immediately:
- Show preview URL (or "No preview available" for metadata-only PRs)
- Categorize changed files by type (Package YAML, Go tools, CI workflows, Build scripts, Infrastructure, Theme/layout, Community packages)
- Generate concrete, actionable review guidance based on actual diff content
This allows users to review the deployment while you perform the comprehensive analysis in Step 5.

Only after displaying output from this step, continue to Step 4.

Step 4: Check for Infrastructure Changes

Check if PR contains infrastructure or CI/CD changes:

Files in infrastructure/
Files in .github/workflows/
Changes to Makefile or scripts/ci/
Changes to origin-bucket-metadata.json

If infrastructure changes detected, flag for careful review and note potential production impact.

Only after displaying output from this step, continue to Step 5.

Step 5: Perform Comprehensive Review

Review all files against registry review criteria: Go code quality, YAML validity, CI workflow correctness, build system compatibility, infrastructure safety, BUILD-AND-DEPLOY.md currency, community package list integrity, and general spelling/grammar/links. See _common:review-criteria for full criteria.

Large diffs (>100 lines): Summarize findings by category rather than line-by-line.

Continue to Step 6.

Step 6: Summarize Review Findings

Present review results in terminal-friendly format:

## Review Summary

**Overall Assessment**: [Clean/Minor issues/Issues found/Critical issues]

### Findings

**[Category]**: [Brief summary]
- Line X: [Issue description]
- Line Y: [Issue description]

### Recommendations

[Specific recommendations based on findings]

Continue to Step 7.

Step 7: Present Action Menu

Use AskUserQuestion (max 4 options) to present the appropriate action menu based on contributor type (bot vs non-bot) and review findings.

See pr-review:references:action-menus for complete menu structures and logic.

Continue to Step 8 with selected action.

Step 8: Preview Planned Actions and Get Confirmation

CRITICAL: Always show what will happen before executing.

See pr-review:references:action-preview-templates for preview formats.

Display preview showing:

Exact comment text that will be posted (using templates from pr-review:references:message-templates)
Commands that will be executed
For "Make changes and approve": Show file-by-file changes

Confirmation options (use AskUserQuestion):

Yes, proceed - Execute as previewed
Edit comment - Modify comment text
Change action - Return to Step 7
Cancel - Exit without changes

Handle each response appropriately:

Edit comment → Show updated preview → Confirm again
Change action → Return to action menu (Step 7)
Cancel → Exit with "No action taken"

Continue to Step 9 with confirmed action.

Step 9: Execute Confirmed Action

Execute using confirmed/edited content from Step 8.

Commands by action:

Approve: gh pr review {{arg}} --approve --body "{{COMMENT}}"
Approve and merge: gh pr review {{arg}} --approve --body "{{COMMENT}}" then gh pr merge {{arg}} --auto --squash
Request changes: gh pr review {{arg}} --request-changes --body "{{COMMENT}}"
Close PR: gh pr comment {{arg}} --body "{{COMMENT}}" then gh pr close {{arg}}
Do nothing yet: Exit with message

Make changes and approve: See pr-review:references:action-preview-templates for complete workflow.

Continue to Step 10.

Step 10: Report Execution Results

See pr-review:references:execution-results for result message templates.

Display appropriate success message with:

Confirmation of action taken
PR URL for easy access
Additional context (bot info, risk tier, deployment warnings)
Verification commands where helpful

Workflow complete.

Critical Workflow Rules

Complete all 10 steps in sequence - Never skip steps or end workflow prematurely
Step 3 timing - Present test deployment guidance BEFORE starting comprehensive review (Step 5)
Step 4 prerequisite - Must complete infrastructure check before Step 5
Always preview before execution - Show exactly what will happen (Step 8) before executing (Step 9)
Use confirmed content - Execute only with user-approved text from Step 8
Track progress - Display [Step X/10] before each step heading
Preserve branch safety - For "Make changes and approve": save current branch, return to it even on errors

Error Recovery

If any command fails during execution:

Failed to [action] PR #{{arg}}

Error: [error message]

Recovery options:
- /pr-review {{arg}} (re-run full workflow)
- Or use gh CLI directly: [relevant commands based on failure]

For "Make changes and approve" failures: Always return to original branch before reporting error.

Pull Request Review

Recommended for