pr-description

A good PR description answers what the diff cannot: why the change was made, what alternatives were rejected, and how it was verified. Structure it with sections for motivation, grouped changes, actual test evidence, and review focus points.

Include the triggering problem or linked issue, changes grouped by logic rather than by file, concrete verification steps you actually ran, and areas reviewers should examine closely. Small PRs can be one sentence, but the verification section should never be skipped.

First ask whether the PR can be split, since review quality drops sharply with size. If splitting is impossible, provide a suggested reading order in the description, starting with type definitions and core logic before mechanical call-site changes.

Yes. Explicitly listing what was not covered tells reviewers where to focus and builds trust. Hiding weaknesses slows review because problems surface later at higher cost.

Common mistakes include restating the diff file by file, writing vague claims like "should be fine", documenting debugging journeys instead of conclusions, and burying breaking changes in the middle of the text without migration guidance.