pull-request

Overview

Authoring PR communication that respects busy reviewers. All bodies and comments are drafted to .scratch/pr-bodies/ for human review before posting. Anti-patterns (metrics, diff-noise, H1 headings) are avoided. Manual edits are detected before overwriting.

Operations

Routing ambiguous requests

"update the PR" is ambiguous:

• No PR exists: error and offer to create
• PR has no reviews: update body
• PR has reviews: ask whether to update body or add a comment

Prefer body update when there are no reviews yet, the user says "update the description", or scope changed. Prefer comment when reviews are in, the user is responding to feedback, or they want to notify watchers (comments generate notifications, body updates do not).

Content principles

Follow repo conventions first

Check for a PR template (.github/pull_request_template.md, .github/PULL_REQUEST_TEMPLATE.md, .github/PULL_REQUEST_TEMPLATE/*.md) and CONTRIBUTING.md (also .github/CONTRIBUTING.md, docs/CONTRIBUTING.md). If a template exists, follow it exactly.

Default body structure (no template)

## Summary

- Material impact point 1
- Material impact point 2 (2-4 bullets total)

## Test plan

- How to verify (only if non-obvious)

Optional sections based on context: ## Breaking changes, ## Migration notes, ## Follow-up work.

PR title

Imperative mood (Add, Fix, Update, Refactor), under 72 characters, capitalize first word, no trailing period. Derive from the branch name when semantic, otherwise from the first commit.

Do

• Focus on material impact and why it matters
• Include non-obvious testing steps
• Stay warm and concise

Don't

Metrics (unless the PR is about them): "Added 15 tests", "Modified 8 files", "Added 250 lines", "Coverage to 85%", "Runtime 2.5s to 1.2s".

Diff-visible details: "Created new Foo class", "Refactored into smaller functions", "Used async/await", "Added error handling" (unless that is the PR's focus).

Over-explaining: "After careful consideration of multiple approaches...", "significantly improves the developer experience by implementing a novel approach...".

Structural noise: H1 heading (GitHub shows the title separately), listing technologies unless a new dependency, file structure changes unless architectural, "following best practices" (assumed), "easy to" / "simple to" (condescending).

The rule: If a reviewer can see it in the diff or CI output, do not put it in the body unless it is the central focus.

Comment tone

Three to five sentences, conversational, professional. Acknowledge reviewer input. Explain reasoning when non-obvious. A common opening pattern: "I've updated the PR to address the feedback: ..."

Workflow: Create PR

1. Check for existing PR: gh pr view --json number 2>/dev/null. If one exists, error or route to update.
2. Gather: git log <base>..HEAD, PR template, CONTRIBUTING.md.
3. Draft body to .scratch/pr-bodies/drafts/<slug>.md. Show the draft to the user and allow edits.
4. Create: gh pr create --title "..." --body-file <draft-path> (add --draft if the user asked for a draft).
5. Archive: move the draft to .scratch/pr-bodies/<number>/<timestamp>-body.md and write metadata.json with the body hash.

Workflow: Update body

1. Load: gh pr view --json number,body,title,state. Load metadata.json if present. Warn if closed or merged.
2. Detect manual edits: hash the current body (shasum -a 256) and compare to last_generated_hash. If different and the diff is more than whitespace, ask: overwrite, merge, or cancel.
3. Check for material change: re-analyze <base>..HEAD. If scope is unchanged from last generation, skip the update and say "description still accurate".
4. Draft to .scratch/pr-bodies/<number>/<timestamp>-body.md. Show the diff (current vs proposed) and confirm.
5. Update: gh pr edit <number> --body-file <file>. Update metadata.json (new hash, timestamp).

Workflow: Comment

1. Load: gh pr view --json number,title,reviews,comments.
2. Determine content. Analyze recent commits. Common scenarios: responding to review feedback, noting significant additions, summarizing a batch of changes.
3. Draft to .scratch/pr-bodies/<number>/<timestamp>-comment.md. Show the draft and confirm.
4. Post: gh pr comment <number> --body-file <file>.

Safety checks

Always: current branch is not main/master; gh is installed and authenticated; the user has seen and approved the draft.

Create: branch has commits ahead of base. Update: PR exists and is open. Comment: comment is not empty.

If gh is missing, fall back with brew install gh. If not authenticated, gh auth login.

Storage layout

.scratch/pr-bodies/
  drafts/
    <slug>.md                # Pre-creation drafts
  <pr-number>/
    metadata.json             # See schema below
    <timestamp>-body.md       # Timestamped body versions
    <timestamp>-comment.md    # Timestamped comments

metadata.json:

{
  "pr_number": 123,
  "branch": "feature/foo",
  "base": "main",
  "title": "Add foo",
  "created_at": "2025-11-07T10:30:00Z",
  "last_generated_hash": "abc123...",
  "last_updated_at": "2025-11-07T16:45:30Z",
  "manual_edits_detected": false
}

Timestamps use ISO 8601 with hyphens (2025-11-07T10-30-00). Slugs are lowercase with hyphens and special chars stripped.

Keep: metadata.json, the last five timestamped files, any in-progress draft. Clean up after PR creation: the draft file. Optional: timestamped files older than 30 days.

Base branch detection

base=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null)
if [ -z "$base" ]; then
  git show-ref --verify --quiet refs/heads/main && base=main || base=master
fi

Multiple PRs for one branch

gh pr list --head <branch> --state open. If exactly one open, use it. If zero, check --state all and offer to create new. If more than one (rare), ask which.

Common mistakes

• Posting the first draft without user review. Always confirm before running gh pr create/edit/comment.
• Overwriting manual edits silently. Always compare hashes and show the diff first.
• Updating body when nothing material changed. Skip with "description still accurate".
• Using raw gh pr create without --body-file. Shell-escaping issues and no draft review step.
• Running create on main/master. Stop and ask the user to branch first.
• Ignoring repeated open PRs on the same branch. Always check gh pr list --head <branch>.