Finalizes any PR for merge by verifying title and description match actual implementation. Reviews existing description quality before suggesting changes. Use when asked to "finalize PR", "check PR description", "review commit message", before merging any PR, or when PR implementation changed during review. Do NOT use for extracting lessons (use learn-from-pr), writing tests (use write-tests-agent), or investigating build failures (use pr-build-status).
Ensures PR title and description accurately reflect the implementation, and performs a code review for best practices before merge.
Standalone skill - Can be used on any PR, not just PRs reviewed by the pr-review skill.
Two-Phase Workflow
Title & Description Review - Verify PR metadata matches implementation
Code Review - Review code for best practices and potential issues
🚨 CRITICAL RULES
1. NEVER Approve or Request Changes
AI agents must NEVER use --approve or --request-changes flags.
Action
Allowed?
Why
gh pr review --approve
❌ NEVER
Approval is a human decision
gh pr review --request-changes
❌ NEVER
Blocking PRs is a human decision
2. NEVER Post Comments Directly
This skill is ANALYSIS ONLY. Never post comments using gh commands.
Action
Allowed?
Why
gh pr review --comment
❌ NEVER
Review-PR.ps1 handles posting via scripts
gh pr comment
❌ NEVER
Review-PR.ps1 handles posting via scripts
Analyze and report findings
✅ YES
This is the skill's purpose
Correct workflow:
This skill: Analyze PR, produce findings and write to pr-finalize-summary.md
Human-controlled follow-up: PR finalization is not part of the automated Review-PR.ps1 flow. Only post or use the summary when a user explicitly asks for PR finalization.
Only humans control when comments are posted. Your job is to analyze and present findings.
Phase 1: Title & Description
Core Principle: Preserve Quality
Review existing description BEFORE suggesting changes. Many PR authors write excellent, detailed descriptions. Your job is to:
Evaluate first - Is the existing description good? Better than a template?
Preserve quality - Don't replace a thorough description with a generic template
Enhance, don't replace - Add missing required elements (NOTE block, issue links) without rewriting good content
Only rewrite if needed - When description is stale, inaccurate, or missing key information
Usage
# Get current state (no local checkout required)
gh pr view XXXXX --json title,body
gh pr view XXXXX --json files --jq '.files[].path'
# Review commit messages (helpful for squash/merge commit quality)
gh pr view XXXXX --json commits --jq '.commits[].messageHeadline'
# Review actual code changes
gh pr diff XXXXX
# Optional: if the PR branch is checked out locally
git diff origin/main...HEAD
Evaluation Workflow
Step 1: Review Existing Description Quality
Before suggesting changes, evaluate the current description:
Quality Indicator
Look For
Structure
Clear sections, headers, organized flow
Technical depth
File-by-file changes, specific code references
Scanability
Easy to find what changed and where
Accuracy
Matches actual diff - not stale or incorrect
Completeness
Platforms, breaking changes, testing info
Step 2: Compare to Template
Ask: "Is the existing description better than what my template would produce?"
If YES: Keep existing, only add missing required elements
If NO: Suggest improvements or replacement
Step 3: Produce Output
Recommended PR title (if change needed)
Assessment of existing description
Specific additions needed (e.g., "Add NOTE block at top")
Only full replacement if description is inadequate
Title Requirements
The title becomes the commit message headline. Make it searchable and informative.
Requirement
Good
Bad
Platform prefix (if specific)
[iOS] Fix Shell back button
Fix Shell back button
Describes behavior, not issue
[iOS] SafeArea: Return Empty for non-ISafeAreaView views
Fix #23892
Captures the "what"
Return Empty for non-ISafeAreaView
Fix SafeArea bug
Notes model change if applicable
(opt-in model)
(omitted)
No noise prefixes
[iOS] Fix...
[PR agent] Fix...
Title Formula
[Platform] Component: What changed (model change if any)
Examples:
[iOS] SafeArea: Return Empty for non-ISafeAreaView views (opt-in model)
[Android] CollectionView: Fix scroll position reset on item update
[Windows] Shell: Use NavigationView instead of custom flyout
Description Requirements
PR description should:
Include the base sections from .github/PULL_REQUEST_TEMPLATE.md ("Description of Change" and "Issues Fixed"). The skill adds additional structured fields (Root cause, Fix, Key insight, etc.) as recommended enhancements for better agent context.
Match the actual implementation
### Description of Change
[Must match actual implementation]
### Issues Fixed
Fixes #XXXXX
Content for Future Agents
The title and description become the commit message. Future agents searching git history will use this to understand:
What changed and why
What patterns to follow or avoid
How this change affects related code
Required Elements for Agent Success
Element
Purpose
Example
Root cause
Why the bug occurred
"Non-ISafeAreaView views falling through to return baseSafeArea"
Fix approach
What the code now does
"Return SafeAreaPadding.Empty for views without interface"
Philosophy/model change
If behavior model changed
"Before: opt-out. After: opt-in via interface"
Key interfaces/types
Types agents need to know
"ISafeAreaView, ISafeAreaView2 = opt-in contract"
What NOT to do
Failed approaches to avoid
"Don't use Element type in Platform layer"
Architectural constraints
Layer boundaries, type availability
"Platform layer cannot reference Controls types"
Edge cases
Known limitations or risks
"Legacy layouts are [Obsolete], custom views need interface"
"What NOT to Do" Section (Critical)
When try-fix or debugging revealed failed approaches, document them:
### What NOT to Do (for future agents)
- ❌ **Don't use [Type] in [Layer]** - [Why it fails]
- ❌ **Don't use [Pattern]** - [Why it's brittle/wrong]
- ❌ **Don't [Approach]** - [Why it doesn't work]
This prevents future agents from repeating failed experiments.
Philosophy/Model Changes
When a fix changes the behavioral model (not just fixing a bug), call it out explicitly:
**This is a philosophy change:**
- **Before:** [Old behavior model]
- **After:** [New behavior model]
Example: "Before: Safe area applied by default (opt-out). After: Only views implementing ISafeAreaView get safe area (opt-in)."
The pr-finalize skill is ANALYSIS ONLY. Never post comments using gh pr review or gh pr comment.
Action
Allowed?
Why
gh pr review --comment
❌ NEVER
Review-PR.ps1 handles posting via scripts
gh pr comment
❌ NEVER
Review-PR.ps1 handles posting via scripts
Analyze and report findings
✅ YES
This is the skill's purpose
Workflow:
This skill: Analyze PR, produce findings and write to pr-finalize-summary.md
Human-controlled follow-up: PR finalization is not part of the automated Review-PR.ps1 flow. Only post or use the summary when a user explicitly asks for PR finalization.
The user controls when comments are posted. Your job is to analyze and present findings.
Complete Example
See references/complete-example.md for a full agent-optimized PR description showing all elements above applied to a real SafeArea fix.
