pr-description

To write a pull request description focused on why changes were made, avoid repeating diffs and instead structure your narrative into Problem, Solution, Design Decisions, Tradeoffs, Verification, and Impact sections. This framework emphasizes the context and rationale behind your code rather than listing modified files.

In a PR description for code review, you should avoid repeating diff contents, listing changed files or classes, pasting commit messages directly, and using mechanical AI summaries. Instead, focus on conveying the design intent, tradeoffs, and context not visible in the diff.

To document a breaking change in a pull request, place a warning at the top of the PR description and move the Impact section immediately after the Problem. The Impact section must explicitly state the before and after states and explain how backward compatibility is maintained in production environments.

The best way to structure a PR description for complex design decisions is to use a Problem, Solution, Design Decisions, Tradeoffs, and Verification format. Detail the chosen approach's rationale, compare it briefly against alternatives, and explicitly state any sacrificed constraints like performance or consistency.

To describe verification and testing in a PR description, use the Verification section to document exactly what tests were run and which validations were performed. You should also honestly state any unverified areas or limitations to set clear expectations for the reviewer.