pr-writer

PR Writer

Create pull requests following conventional engineering practices.

Requires: GitHub CLI (gh) authenticated and available.

Prerequisites

Before creating a PR, ensure all changes are committed. If there are uncommitted changes, run the commit skill first to commit them properly.

# Check for uncommitted changes
git status --porcelain

If the output shows any uncommitted changes (modified, added, or untracked files that should be included), invoke the commit skill before proceeding.

Process

Step 1: Verify Branch State

# Detect the default branch — note the output for use in subsequent commands
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

# Check current branch and status (substitute the detected branch name above for BASE)
git status
git log BASE..HEAD --oneline

Ensure:

• All changes are committed
• Branch is up to date with remote
• Changes are rebased on the base branch if needed

Step 2: Analyze Changes

Review what will be included in the PR:

# See all commits that will be in the PR (substitute detected branch name for BASE)
git log BASE..HEAD

# See the full diff
git diff BASE...HEAD

Understand the scope and purpose of all changes before writing the description.

Step 3: Write the PR Description

Use this structure for PR descriptions (ignoring any repository PR templates):

<brief description of what the PR does>

<why these changes are being made - the motivation>

<alternative approaches considered, if any>

<any additional context reviewers need>

Do NOT include:

• "Test plan" sections
• Checkbox lists of testing steps
• Redundant summaries of the diff

Do include:

• Clear explanation of what and why
• Links to relevant issues or tickets
• Context that isn't obvious from the code
• Notes on specific areas that need careful review

For non-trivial PR prose, use style-review as an opt-in polish pass before the body is finalized. The pass must review a draft copy and must not mutate the source draft unless the user explicitly accepts edits.