pr-description-writer

PR Description Writer

Read the current branch diff and write a complete GitHub pull request description. Create or update the PR with one command.

Writing Style

Apply to all generated PR descriptions:

• Active voice. "Adds X" not "X has been added."
• Present tense for summary ("Adds caching layer"), past tense for context ("The old approach caused N requests per render")
• Short sentences, one idea per bullet
• No em dashes — use a comma or period instead
• No filler: "this PR", "this commit", "as per the discussion"
• Specifics beat generalities: "reduces p95 latency from 800ms to 90ms" beats "improves performance"

---

Step 1: Check Setup

Confirm gh is authenticated:

gh auth status

If not authenticated: gh auth login and follow the prompts.

Confirm the current directory is a git repo with an active branch:

git branch --show-current

If detached HEAD or no branch, stop and ask the user which branch they want to describe.

---

Step 2: Gather Diff Context

Run all three commands to build context:

File summary (what changed):

git diff main...HEAD --stat

Commit messages (why it changed):

git log main...HEAD --oneline

Full diff (how it changed):

Use origin/main first (always up to date), fall back to local main, then master:

if git rev-parse origin/main &>/dev/null 2>&1; then
  BASE=origin/main
elif git rev-parse main &>/dev/null 2>&1; then
  BASE=main
else
  BASE=master
fi
git diff $BASE...HEAD

If the diff is very large (over 500 lines), read the --stat summary and the commit messages only. Also read the first 200 lines of the diff to understand the primary changes without processing the entire output.

Also check for an existing PR and read its current title/body:

gh pr view --json title,body,baseRefName 2>/dev/null

---

Step 3: Read the Format Guide

Read references/pr-format-guide.md in full before writing anything. Internalize:

• Required sections and their order
• How to write each section
• What to include vs omit
• The testing section format