pr-explainer

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:

1. Hero

   • PR number/title, one-sentence summary, branch/link/status.
   • Small metrics: files changed, tests added, packages affected.

2. Problem

   • Previous behavior.
   • Why it was wrong, confusing, missing, or risky.

3. System Context

   • Where the change sits in the product or architecture.
   • Upstream callers, downstream behavior, and why this is the right layer.
   • Behavior intentionally not changed.

4. Before/After Flow

   • Visual old path vs. new path when the PR changes flow, state, ownership, permissions, request handling, data transformation, or component relationships.

5. Code Walkthrough

   • Step-by-step explanation path.
   • Focused diffs for important files only.
   • Explain what each snippet accomplishes and why it is necessary.

6. Tests / Verification

   • Tests added or updated.
   • Commands run for tests, build, typecheck, lint, or manual verification.
   • Known unrelated warnings or failures, if any.

7. Reviewer Takeaway

   • The shortest useful mental model of the PR.
   • What the reviewer should focus on while reviewing the actual diff.

Diagrams

Add diagrams when they reduce cognitive load. Prefer simple HTML/CSS diagrams over external dependencies.

Good diagram types:

• Request flow: Client → Server → Handler → Service → Result
• Before/after path: broken path vs. fixed path
• Ownership map: package/module responsibility boundaries
• Data transformation: input → normalized form → output
• State machine: pending → running → complete/error

Each diagram must answer: “What does this help the reviewer understand faster?”

Focused diff snippets

Show snippets along the explanation path, not giant patches. Each important snippet should include:

• file path,
• relevant added/removed lines only,
• visual styling for additions/removals,
• a short explanation,
• connection back to the PR story.

Use this pattern:

<div class="diff">
  <div class="diff-title">packages/example/src/file.ts</div>
  <pre>
<span class="del">- old behavior</span>
<span class="add">+ new behavior</span>
  </pre>
</div>

A reviewer should understand the PR without opening GitHub, but the page should not replace the final full diff review.

Verification requirements

End with proof. Include exact commands when available, for example:

pnpm --filter @scope/package test path/to/test.ts -- --run
pnpm turbo build --filter ./packages/package

If verification was not run, say so clearly and list the recommended commands.

Final checklist

Before calling the page done, confirm it has:

• clear one-sentence summary,
• problem statement,
• before/after explanation,
• broader system context,
• visual diagram where useful,
• step-by-step code walkthrough,
• focused diffs with file paths,
• tests and verification commands,
• reviewer takeaway,
• self-contained HTML/CSS,
• stored in .pr-review/,
• not staged or committed unless explicitly requested.

Default output

When asked to create a PR explainer, produce or update a .pr-review/*.html file and summarize:

1. output path,
2. PR story covered,
3. key sections included,
4. verification evidence included,
5. whether .pr-review/ remains untracked or excluded.