pr-design-doc - a reviewable design doc for a non-trivial PR

A diff shows what changed line by line. It does not show the design: the shape of the change, the API before and after, and why this approach. Reviewers reconstruct that by hand, slowly. The scarce resource is the maintainer's attention and trust budget - not the agent's effort. Spend extra effort to hand them one self-contained HTML page that conveys the big picture and the before → after core difference, with every claim clickable back to the real code, then link it from the PR description.

This is the same craft as a "show me this change" explainer, aimed at one job: making a non-trivial PR easy to review.

When to use it