PR Explainer

Create a local, self-contained HTML page that teaches a reviewer the PR story: what changed, why it matters, how it works, how it fits into the system, and how it was verified.

Required workflow

1. Understand the PR before writing HTML

   • Collect PR title/number, branch, link if available, base branch, commit range, changed files, and verification already performed.
   • Inspect the current state with git status --short.
   • Inspect recent commits with git log --oneline -n 10.
   • Inspect scope with git diff <base>...HEAD --stat and git diff <base>...HEAD.
   • If one commit carries the main change, inspect it with git show --stat <commit> and git show <commit>.

2. Find the explanation path

   • Do not explain files in raw diff order.
   • Teach the change in this order when possible:
     1. problem,
     2. system context,
     3. before/after data or control flow,
     4. key code changes,
     5. proof from tests/builds/manual checks,
     6. reviewer takeaway.
   • Classify changed files as core behavior, plumbing/integration, tests, release metadata, or incidental noise.
   • Highlight only files that help explain the PR.

3. Write for approachability

   • Use plain language, short sections, concrete before/after examples, small focused snippets, diagrams, tables, and callouts.
   • Explain the problem before implementation details.
   • Define acronyms or package-specific terms before using them.
   • Avoid dumping the full diff or assuming the reviewer already knows internal context.

4. Create a local self-contained HTML file

   • Put generated files in .pr-review/.
   • Use one HTML file containing all CSS and content.
   • Do not commit .pr-review/ by default.
   • Prefer repo ignore rules or .git/info/exclude so generated review pages stay out of commits.

Recommended HTML structure

Use this structure unless the PR clearly needs a different teaching order: