PR Finalize

Ensures PR title and description accurately reflect the implementation for a good commit message.

Works on any PR - Does not require agent involvement or session markdown.

Inputs

Input	Required	Source
PR number	Yes	User provides
Session markdown	Optional	.github/agent-pr-session/issue-XXXXX.md or pr-XXXXX.md

Outputs

1. Recommended PR title - Platform prefix, behavior-focused
2. Recommended PR description - NOTE block + structured content
3. Session markdown updates (only if file exists)

Completion Criteria

• Reviewed PR diff to understand actual implementation
• Verified title matches implementation (or recommended fix)
• Verified description matches implementation (or recommended fix)
• Checked for session markdown and updated if needed

When to Use

• Before merging any PR
• "Finalize PR #XXXXX"
• "Check PR description for #XXXXX"
• When implementation changed during review

When NOT to Use

• ❌ For analyzing lessons learned (use learn-from-pr skill instead)
• ❌ For writing or running tests (use write-tests or sandbox)
• ❌ For investigating why PR build failed (use pr-build-status)

Constraints

• Don't change PR title/description directly - Only recommend changes
• Don't modify code - Only verify title/description accuracy
• Match existing style - Follow PR template format
• Preserve user content - Enhance, don't replace custom descriptions

---

Workflow

Step 1: Get PR State

gh pr view XXXXX --json title,body,files
gh pr diff XXXXX
gh pr view XXXXX --json commits --jq '.commits[].messageHeadline'

Step 2: Analyze Implementation

Read the diff and understand:

• What was actually changed (not what was planned)
• Which platforms are affected
• What the fix does

Step 3: Verify Title

Requirement	Good	Bad
Platform prefix (if specific)	[iOS] Fix Shell back button	Fix Shell back button
Describes behavior	Fix long-press not triggering events	Fix #23892
No noise prefixes	[iOS] Fix...	[PR agent] Fix...

Step 4: Verify Description

Must include:

1. NOTE block (for testing PR artifacts)
2. Description of Change (matches actual implementation)
3. Issues Fixed

Should include (for agent context):

• Root cause
• Fix approach
• Key insight

Step 5: Session Markdown (If Exists)

ls .github/agent-pr-session/issue-XXXXX.md .github/agent-pr-session/pr-XXXXX.md 2>/dev/null

If file exists:

• Check if "Selected Fix: [PENDING]" → update with actual fix
• Add "ACTUAL IMPLEMENTED FIX" section if missing
• Document lessons learned

If file doesn't exist: Skip this step.

Step 6: Present Recommendations

Output recommended title and description.

---

Error Handling

Situation	Action
PR not found	Ask user to verify PR number
No session markdown	Proceed - only verify title/description
Title already good	Confirm it's good, no change needed
Description missing	Generate recommended description

---

Output Template

# PR Finalize: #XXXXX

## Title Assessment
**Current:** [current title]
**Recommendation:** [recommended title, or "✅ Current title is good"]

## Description Assessment
**Issues:**
- [issue 1]
- [issue 2]

**Recommended Description:**

<!-- Please let the below note in for people that find this PR -->
> [!NOTE]
> Are you waiting for the changes in this PR to be merged?
> It would be very helpful if you could [test the resulting artifacts](https://github.com/dotnet/maui/wiki/Testing-PR-Builds) from this PR and let us know in a comment if this change resolves your issue. Thank you!

### Description of Change

[Brief summary matching implementation]

**Root cause:** [Why bug occurred]

**Fix:** [What code now does]

### Issues Fixed

Fixes #XXXXX

## Session Markdown
[Updated / No file exists / Already complete]

---

Title Requirements

• Platform prefix if platform-specific: [iOS], [Android], [Windows], [MacCatalyst]
• Behavior-focused - Describe what changed, not issue number
• Concise - Should fit in commit message subject line

Description Requirements

Required Sections

<!-- Please let the below note in for people that find this PR -->
> [!NOTE]
> Are you waiting for the changes in this PR to be merged?
> It would be very helpful if you could [test the resulting artifacts](https://github.com/dotnet/maui/wiki/Testing-PR-Builds) from this PR and let us know in a comment if this change resolves your issue. Thank you!

### Description of Change
[Must match actual implementation]

### Issues Fixed
Fixes #XXXXX

Recommended Additions (for agent context)

Element	Purpose
Root cause	Why the bug occurred
Fix approach	What the code now does
Key insight	Non-obvious understanding
What to avoid	Patterns that would re-break

---

Session Markdown Updates (Optional)

If session markdown exists and is incomplete, add:

## ACTUAL IMPLEMENTED FIX

**Selected Fix:** [Brief description]

**What was implemented:**
1. [What changed]
2. [Key files]

**Key insight:** [Non-obvious understanding]

## Lessons Learned

**What would have helped:**
1. [Suggestion 1]
2. [Suggestion 2]

---

Common Issues

Problem	Solution
Description doesn't match code	Rewrite from actual diff
Missing root cause	Add from issue/analysis
References wrong approach	Update to describe final approach
"Selected Fix: [PENDING]"	Document actual implementation

---

Example

PR #33352 - MacCatalyst crash on window disposal

Step 1: Get PR State

gh pr view 33352 --json title,body,files
# Title: "Fix ObjectDisposedException in PageViewController"
# Files: PageViewController.cs

Step 2: Analyze Implementation

• Fix adds null check for window.Handler before accessing services
• Platform: MacCatalyst specific
• Prevents crash during TraitCollectionDidChange when window disposed

Step 3: Verify Title

• Current: "Fix ObjectDisposedException in PageViewController"
• Assessment: Missing platform prefix
• Recommended: [MacCatalyst] Fix ObjectDisposedException in PageViewController.TraitCollectionDidChange

Step 4: Verify Description

• Missing NOTE block
• Missing root cause explanation
• Generate recommended description

Output:

# PR Finalize: #33352

## Title Assessment
**Current:** Fix ObjectDisposedException in PageViewController
**Recommendation:** [MacCatalyst] Fix ObjectDisposedException in PageViewController.TraitCollectionDidChange

## Description Assessment
**Issues:**
- Missing NOTE block for testing PR artifacts
- Missing root cause explanation

**Recommended Description:**
[Full description with NOTE block, root cause, fix approach...]

## Session Markdown
Updated - Added "ACTUAL IMPLEMENTED FIX" section

---

Integration

• pr-finalize → Verify PR ready to merge (this skill)
• learn-from-pr → Extract lessons after finalization
• learn-from-pr agent → Extract lessons AND apply improvements