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
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>.
Find the explanation path
- Do not explain files in raw diff order.
- Teach the change in this order when possible:
- problem,
- system context,
- before/after data or control flow,
- key code changes,
- proof from tests/builds/manual checks,
- reviewer takeaway.
- Classify changed files as core behavior, plumbing/integration, tests, release metadata, or incidental noise.
- Highlight only files that help explain the PR.
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.
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:
Hero
- PR number/title, one-sentence summary, branch/link/status.
- Small metrics: files changed, tests added, packages affected.
Problem
- Previous behavior.
- Why it was wrong, confusing, missing, or risky.
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.
Before/After Flow
- Visual old path vs. new path when the PR changes flow, state, ownership, permissions, request handling, data transformation, or component relationships.
Code Walkthrough
- Step-by-step explanation path.
- Focused diffs for important files only.
- Explain what each snippet accomplishes and why it is necessary.
Tests / Verification
- Tests added or updated.
- Commands run for tests, build, typecheck, lint, or manual verification.
- Known unrelated warnings or failures, if any.
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:
- output path,
- PR story covered,
- key sections included,
- verification evidence included,
- whether
.pr-review/ remains untracked or excluded.
1---2name: pr-explainer3description: Use when creating an approachable, self-contained HTML review aid for a pull request; explaining what changed, why it matters, how it works, and how it fits into the broader system; turning PR diffs, commits, tests, and architecture context into a local `.pr-review/` HTML page for reviewers; or helping reviewers understand complex code changes without dumping the full diff.4---5
6# PR Explainer
7
8Create 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.
9
10## Required workflow
11
121. **Understand the PR before writing HTML**
13 - Collect PR title/number, branch, link if available, base branch, commit range, changed files, and verification already performed.
14 - Inspect the current state with `git status --short`.
15 - Inspect recent commits with `git log --oneline -n 10`.
16 - Inspect scope with `git diff <base>...HEAD --stat` and `git diff <base>...HEAD`.
17 - If one commit carries the main change, inspect it with `git show --stat <commit>` and `git show <commit>`.
18
192. **Find the explanation path**
20 - Do not explain files in raw diff order.
21 - Teach the change in this order when possible:
22 1. problem,
23 2. system context,
24 3. before/after data or control flow,
25 4. key code changes,
26 5. proof from tests/builds/manual checks,
27 6. reviewer takeaway.
28 - Classify changed files as core behavior, plumbing/integration, tests, release metadata, or incidental noise.
29 - Highlight only files that help explain the PR.
30
313. **Write for approachability**
32 - Use plain language, short sections, concrete before/after examples, small focused snippets, diagrams, tables, and callouts.
33 - Explain the problem before implementation details.
34 - Define acronyms or package-specific terms before using them.
35 - Avoid dumping the full diff or assuming the reviewer already knows internal context.
36
374. **Create a local self-contained HTML file**
38 - Put generated files in `.pr-review/`.
39 - Use one HTML file containing all CSS and content.
40 - Do not commit `.pr-review/` by default.
41 - Prefer repo ignore rules or `.git/info/exclude` so generated review pages stay out of commits.
42
43## Recommended HTML structure
44
45Use this structure unless the PR clearly needs a different teaching order:
46
471. **Hero**
48 - PR number/title, one-sentence summary, branch/link/status.
49 - Small metrics: files changed, tests added, packages affected.
50
512. **Problem**
52 - Previous behavior.
53 - Why it was wrong, confusing, missing, or risky.
54
553. **System Context**
56 - Where the change sits in the product or architecture.
57 - Upstream callers, downstream behavior, and why this is the right layer.
58 - Behavior intentionally not changed.
59
604. **Before/After Flow**
61 - Visual old path vs. new path when the PR changes flow, state, ownership, permissions, request handling, data transformation, or component relationships.
62
635. **Code Walkthrough**
64 - Step-by-step explanation path.
65 - Focused diffs for important files only.
66 - Explain what each snippet accomplishes and why it is necessary.
67
686. **Tests / Verification**
69 - Tests added or updated.
70 - Commands run for tests, build, typecheck, lint, or manual verification.
71 - Known unrelated warnings or failures, if any.
72
737. **Reviewer Takeaway**
74 - The shortest useful mental model of the PR.
75 - What the reviewer should focus on while reviewing the actual diff.
76
77## Diagrams
78
79Add diagrams when they reduce cognitive load. Prefer simple HTML/CSS diagrams over external dependencies.
80
81Good diagram types:
82
83- Request flow: Client → Server → Handler → Service → Result
84- Before/after path: broken path vs. fixed path
85- Ownership map: package/module responsibility boundaries
86- Data transformation: input → normalized form → output
87- State machine: pending → running → complete/error
88
89Each diagram must answer: “What does this help the reviewer understand faster?”
90
91## Focused diff snippets
92
93Show snippets along the explanation path, not giant patches. Each important snippet should include:
94
95- file path,
96- relevant added/removed lines only,
97- visual styling for additions/removals,
98- a short explanation,
99- connection back to the PR story.
100
101Use this pattern:
102
103```html
104<div class="diff">
105 <div class="diff-title">packages/example/src/file.ts</div>
106 <pre>
107<span class="del">- old behavior</span>
108<span class="add">+ new behavior</span>
109 </pre>
110</div>
111```
112
113A reviewer should understand the PR without opening GitHub, but the page should not replace the final full diff review.
114
115## Verification requirements
116
117End with proof. Include exact commands when available, for example:
118
119```text
120pnpm --filter @scope/package test path/to/test.ts -- --run
121pnpm turbo build --filter ./packages/package
122```
123
124If verification was not run, say so clearly and list the recommended commands.
125
126## Final checklist
127
128Before calling the page done, confirm it has:
129
130- clear one-sentence summary,
131- problem statement,
132- before/after explanation,
133- broader system context,
134- visual diagram where useful,
135- step-by-step code walkthrough,
136- focused diffs with file paths,
137- tests and verification commands,
138- reviewer takeaway,
139- self-contained HTML/CSS,
140- stored in `.pr-review/`,
141- not staged or committed unless explicitly requested.
142
143## Default output
144
145When asked to create a PR explainer, produce or update a `.pr-review/*.html` file and summarize:
146
1471. output path,
1482. PR story covered,
1493. key sections included,
1504. verification evidence included,
1515. whether `.pr-review/` remains untracked or excluded.
mastra-ai