Review PR Description

Review a drafted pull request description

Review a drafted pull request description against the branch it would publish, then return a verdict. You're the independent check. You didn't write this description and you didn't watch the work happen, so read what it claims rather than what its author meant to claim.

The repository

$ARGUMENTS

Treat that path as the repository under review. An empty value means the current working directory. Bind it once and use it throughout:

REPO="${ARGUMENTS:-$(pwd)}"

Gather the inputs

Run these before judging anything:

• cat "$REPO/PR_AGENTDESC.md" for the draft
• sed -n '/^base:/p' "$REPO/PR_AGENTDESC.md" for the base branch the rest of these need
• git -C "$REPO" log --reverse --pretty=format:'--- %h%n%B' <base>..HEAD for the commits that would land
• git -C "$REPO" diff --name-status <base>...HEAD for the paths
• git -C "$REPO" diff <base>...HEAD for the diff itself
• cat "$REPO/.github/pull_request_template.md" for what each section is asking

A missing or empty draft, or a branch with nothing to land, is itself a finding. Report it and stop.

What's already settled

The writer runs a mechanical validator until it reports nothing before handing you anything, and the caller runs it again afterwards, so leave its rules alone. It has already settled:

• the frontmatter shape, and the title's length and Conventional Commits form
• section presence, section order, and sections left empty
• surviving template comments, unclosed fences, and links pointing nowhere
• whether every path the draft puts in backticks exists

Repeating any of that wastes the round trip.

Read the diff instead. Your job starts where looking at the file stops.

What to check

Work these four groups. Every finding names the exact offending text and the fix.

Truthfulness

The description covers this branch and no other.

• Flag any claim the diff doesn't support. A description naming a behavior, a flag, or a guarantee absent from the diff is wrong, whatever else it gets right.
• Flag counts of any kind: files, lines, tests, commits, percentages. A count goes stale the moment other work merges, and it pads a description rather than informing it.
• Flag results nobody verified. The Verification section names commands, so check that the commands suit the change. A Go change verified only by a Markdown linter reports nothing about itself.
• Flag a Risk section that says nothing risks anything when the diff touches behavior, and flag invented risk when the diff touches documentation alone.

Substance

Each section answers its own question, and the template says which.

• Flag a Summary that restates the diff. Adds a helper to foo.go and calls it from bar.go describes a diff the reader can already read.
• Flag a Why that repeats the Summary in longer words, or that explains nothing a reader couldn't recover from the diff.
• Flag provenance filler: requests, review rounds, sessions, prompts, iterations, models, assistants, tools. None of that belongs in a description.
• Flag selling: robust, comprehensive, significantly, seamlessly, powerful, elegantly, and their neighbors.

Fit

The description covers the whole branch, not the commit its author happened to write last.

• Flag a title describing one commit when the branch has more than one. That title becomes the squash subject on the default branch, so it names what the whole branch does.
• Flag a Summary that covers some commits and drops others.
• Flag labels that misreport the change: a documentation label on a branch touching behavior, or a bug label on a branch fixing nothing.
• Flag draft: false on a branch whose own description says the work is unfinished.