TL;DR — Commit messages describe your intentions. The diff describes reality. They drift apart over the life of a branch, and most AI PR-description tools summarize the wrong one. A good PR agent reads the diff. Here's the design, and a free agent to start from.
The PR description that lied
A reviewer pinged me on a PR last year: "The description says this adds rate limiting, but I'm looking at the diff and it also changes how we hash session tokens. Was that intentional?"
It was intentional. I'd done both on the same branch. But my PR description only mentioned the rate limiting — because I'd generated it from my commit messages, and my commit messages were wip, rate limit middleware, fix, fix again, and tweak. The token-hashing change rode in under fix again. The tool that wrote my description faithfully summarized my commits, and my commits faithfully hid half of what I'd actually done.
The reviewer caught it. But the whole point of a PR description is that the reviewer shouldn't have to reconstruct the change from the diff themselves. That's the job I was supposed to have done.
