PR Description from Diff

What you'll build

A small script (or GitHub Action) that reads your branch diff and outputs a reviewer-ready PR description — not a generic AI summary, but your team's exact sections with a real test plan and honest risks.

Why this matters

Review latency is often "waiting for context," not "reading code." A good PR body answers:

• What changed (user-visible)
• Why now
• How to verify
• What could go wrong

Developers skip writing this because it's tedious. LLMs are unusually good at it when you give them the diff and a rigid template. The failure mode is trusting output blindly — 30 seconds of human edit beats 15 minutes of reviewer archaeology.

Architecture

git diff main...HEAD
  + commit messages + changed paths + linked issue
    → LLM (template-locked prompt)
      → Markdown PR body
        → gh pr create / GitHub UI / Action

Pair with GitHub Copilot PR tools or Claude Code hooks — same prompt, different surface.

Step 1 — PR template

Create .github/pull_request_template.md:

## Summary

## Changes

## Test plan

## Risks

Mirror the same headings in your generator's system prompt. Reviewers and the model should see identical structure.

Add conventions inline:

• Test command: npm test / pytest / go test ./...
• Breaking changes require migration steps in Risks
• UI PRs need screenshot checklist in Test plan

Step 2 — Capture context

Minimal shell collector:

#!/usr/bin/env bash
set -euo pipefail
BASE="${1:-main}"
COMMITS=$(git log --oneline "${BASE}...HEAD")
FILES=$(git diff --name-only "${BASE}...HEAD")
DIFF=$(git diff "${BASE}...HEAD")
STAT=$(git diff --stat "${BASE}...HEAD")

# Optional: linked issue from branch name feat/1234-foo
ISSUE=$(gh issue view 1234 --json body -q .body 2>/dev/null || echo "")

Cap diff size. If wc -c exceeds ~300KB, run the "large diff — summarize first" prompt on file list + stat, then describe per group.

Step 3 — Generate

Call your model with the PR description generator prompt (see frontmatter). Rules that matter:

1. Diff wins — don't claim features not in the diff.
2. Checkboxes — Test plan must be executable steps.
3. Risks — prefer "none identified" over silence on large PRs.

Example local runner sketch (Node + Anthropic):

import Anthropic from "@anthropic-ai/sdk";
import { readFileSync } from "fs";

const template = readFileSync(".github/pull_request_template.md", "utf8");
const client = new Anthropic();

const msg = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 2048,
  system: `You write PR bodies for this repo. Template:\n${template}`,
  messages: [{ role: "user", content: buildUserPrompt({ commits, files, diff, issue }) }],
});

console.log(msg.content[0].type === "text" ? msg.content[0].text : "");

For high volume, default to Haiku or Gemini Flash — see cheapest AI APIs.

Step 4 — Human review (non-optional)

Scan for:

• Invented endpoints or flags
• Test steps that don't exist ("run e2e suite" when you only ran unit tests)
• Missing BREAKING callouts on API changes

Fixing one hallucinated checkbox is cheaper than a reviewer chasing a ghost test.

Step 5 — Wire it up

Option A — CLI before push

npm run pr-describe > /tmp/pr-body.md
gh pr create --title "$(npm run pr-title --silent)" --body-file /tmp/pr-body.md

Option B — GitHub Action on pull_request: opened for draft PRs only — posts a comment "Suggested description" or updates body if empty. Reuse the pattern from AI Code Reviewer for Action scaffolding.

Option C — Copilot UI — paste the generator rules into your first Copilot Chat message when drafting the PR on GitHub.

Option D — Claude Code hook — PostToolUse on git push opens the description in your editor.

Large PR strategy

Monorepo tip: pass packages/foo as scope so Changes stays readable.

Extending

• Auto labels — model suggests area:api, risk:high from diff paths.
• Changelog entry — second prompt for CHANGELOG.md semver section.
• Linear/Jira sync — pull ticket acceptance criteria into Test plan checkboxes.
• Pair with review bot — AI Code Reviewer runs after description is set.

Operating cost

At 20 PRs/week and $0.02/run, inference costs **$1.60/month**. The win is reviewer time, not token savings. The highest ROI AI workflow for most engineering teams is "better PR hygiene" — this is the implementation.