/finalize - updates the original PR description to match the current state of the branch and surface anything interesting from the comments. Run this after after addressing substantial feedback on a PR.

finalize.md

name	description
Finalize PR	Updates a PR description after code review to reflect changes and highlight important discussions, edits, or changes.

Update a PR description to reflect the current state after code review discussions.

Step 1: Fetch PR data

Get the PR details and all discussion threads:

# Get PR metadata and body
gh pr view <PR_NUMBER> --json number,title,body,headRefName,baseRefName

# Get all review comments (inline code comments)
gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments --paginate

# Get all reviews (top-level review comments)
gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/reviews --paginate

# Get issue comments (general PR discussion)
gh api repos/{owner}/{repo}/issues/<PR_NUMBER>/comments --paginate

Step 2: Analyze discussions

Read through all comments and identify:

1. Design decisions - Debates about approach, architecture, or implementation that reached a conclusion
2. Scope changes - Features added, removed, or deferred based on feedback
3. Important context - Non-obvious explanations of "why" something was done a certain way
4. Follow-up work - Anything explicitly deferred to a future task

Skip:

• Routine code style feedback
• Typo fixes
• Approval comments without substance

Step 3: Draft updated description

Create an updated PR description that:

1. Preserves the original structure - Keep existing sections intact unless they're now inaccurate
2. Fixes inaccuracies - Update any statements that no longer reflect the final implementation
3. Adds a "Review decisions" section (if needed) at the bottom with:
   • Brief bullet points summarizing key decisions
   • Context on why decisions were made
   • Links to Linear tasks for deferred work (if any were created)

Format for the new section:

## Review decisions

- **[Topic]**: [Brief summary of what was decided and why]
- **[Topic]**: [Brief summary of what was decided and why]

Only add this section if there are meaningful decisions to document. Don't add it for routine feedback.

Step 4: Present diff to user

Show the user a diff of the proposed changes:

## Current description:
[original body]

## Proposed changes:
[summary of what will change]

## New description:
[full new body]

Ask for confirmation before updating.

Step 5: Update the PR

After user confirmation:

gh pr edit <PR_NUMBER> --body "<NEW_BODY>"

Output

## PR Description Updated

**PR #<NUMBER>: <TITLE>**

### Changes made:
- [List of changes to description]

### Review decisions added:
- [List of decisions documented, or "None - no significant decisions to document"]