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.

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.

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.

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?”

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.

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.

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.

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.