| name | explain-pr |
| description | Generate a visual local webpage that explains a GitHub PR as a decision and behavior change, not a defect-finding review. Use when the user asks to understand a PR, asks what a PR is doing, wants a walkthrough, wants a plan-review-style assessment, or wants root problem, before/after examples, tradeoffs, compatibility risks, proof gaps, and reviewer questions. |
Explain PR
Produce a visual, reviewer-facing webpage that explains a GitHub PR.
This skill is not for posting GitHub comments and is not primarily a code-defect
review. It helps a human reviewer understand the problem, the chosen solution
shape, the tradeoffs, and the behavioral or compatibility risks before deciding
whether deeper code review is needed.
Use review-pr when the user wants draft or posted GitHub review comments. Use
request-review when the user wants findings-first technical review.
Inputs
Accept:
- a GitHub PR URL
- a PR number in the current repo
- "this PR" when the active checkout clearly points at a PR branch
If the PR cannot be identified from local context, ask for the URL or number.
Gather Context
Use gh for GitHub context:
gh pr view <number> --json title,body,author,baseRefName,headRefName,headRefOid,files,additions,deletions,commits,reviewDecision
gh pr diff <number>
gh pr checks <number>
For GitHub URLs, derive owner, repo, and number, then use gh api or gh pr view --repo <owner>/<repo> as needed.
Read the PR description first, but do not treat it as complete or neutral.
Compare it against the changed files and tests. If the PR references an issue,
design note, release note, or linked discussion that is central to the stated
problem, fetch that too.
Keep setup read-only. Do not rebase, merge, checkout, reset, or edit files
unless the user separately asks for implementation work.
Analysis Lens
Focus on decisions and consequences:
- What root problem is this PR solving?
- What behavior or workflow existed before?
- What model does the PR introduce after?
- Which decision did the PR make, and what alternatives did it reject?
- What becomes easier, stricter, lazier, earlier, later, broader, narrower, or
more generated?
- What could break for users, maintainers, generated SDKs, integrations, or
existing state?
- What evidence proves the model, and what remains unproven?
Prefer concrete visuals over prose:
- real snippets from the PR over line references
- before/after examples over abstract descriptions
- diagrams, timelines, and flow cards over paragraphs
- tables and matrices over bullet lists
- small user-code, schema, state, config, CLI, or pseudocode examples over file
narration
Use file paths and line references only as supporting labels for snippets or
evidence, not as the primary explanation.
Do not spend the brief walking file-by-file unless the file structure is itself
part of understanding the decision.
Pulumi Provider Lens
When the PR is in a Pulumi provider, bridge, SDK, or related tooling repo, also
classify the touched layer:
- upstream provider behavior or patches
- Pulumi provider runtime behavior
- bridge mapping, schema generation, or token/default fixups
- generated SDK/API surface
- lifecycle behavior such as preview, update, refresh, import, diff, check,
replacement, or provider configuration
- examples, docs, CI, or release tooling
Call out compatibility surfaces that human reviewers commonly need to
pressure-test:
- schema shape, token names, enum/value changes,
oneOf changes, requiredness,
defaults, aliases, autonaming, and deleted outputs
- generated SDK source or binary compatibility
- existing stack upgrade behavior and state migration
- import/refresh behavior versus new-create behavior
- provider-vs-bridge-vs-upstream ownership boundaries
- generated or mechanical diffs that should not distract from the decision
Webpage Output
Create a self-contained local HTML file and give the user the URL or absolute
file path. Markdown is only for the short final status message.
Use a page structure like this, adapting to the PR:
- Hero: title, PR number, author, base/head, size badges, and one-sentence
read.
- Problem Exhibit: the root problem with a concrete before example. Use a
snippet, state shape, API call, CLI output, lifecycle trace, or diagram.
- Before / After: side-by-side cards showing old and new behavior. Prefer
real examples from the PR over paraphrase.
- How It Works: a visual flow, timeline, dependency graph, or short
pseudocode block that explains the mechanism.
- Decision Table: chosen approach, tradeoff, rejected alternative, reviewer
pressure point.
- Compatibility Map: user-visible, maintainer-visible, generated,
lifecycle, and operational risks.
- Proof Board: tests, examples, generated outputs, CI checks, and the exact
behavior each proves.
- Gaps And Questions: visual callouts for unresolved assumptions and the
questions a human reviewer should answer before approving.
Prefer:
- split-screen before/after panels
- sequence diagrams with CSS boxes or inline SVG
- matrix tables for compatibility and proof
- collapsible sections for mechanical generated diffs
- syntax-highlighted or clearly styled code snippets
- badges for layers touched, risk level, and proof strength
Avoid:
- long paragraphs
- file-by-file diff narration
- raw line-reference lists without snippets
- dumping the whole PR diff into the page
The page should be useful when opened independently later. Include enough PR
metadata and links that the artifact is self-contained.
HTML Implementation
Default to a single HTML file under /tmp, such as
/tmp/explain-pr-<owner>-<repo>-<number>.html. Inline CSS and small scripts so
the page can be opened directly.
If the page benefits from local serving and HERDR_ENV=1, load the Herdr
skill, start the server in a non-focused sibling pane, wait for readiness, and
report both the pane and URL. Re-list panes before acting because Herdr pane IDs
are not durable.
Outside Herdr, use a detached tmux session:
tmux new-session -d -s explain-pr-server \
'cd /tmp && python3 -m http.server 8432 --bind 127.0.0.1'
If that port is busy, try 8433, 8434, and so on. Reuse or choose a unique
tmux session name when one already exists. Close the Herdr pane or tmux session
when the server is no longer useful; do not leave unnecessary servers running
when the user only needs the file.
Use HTML escaping for snippets. If embedding patch or PR data into a script tag,
serialize through JSON and replace literal <, >, and & with Unicode
escapes so </script> in source code cannot break the page.
Boundaries
- Do not post GitHub comments.
- Do not convert the brief into a findings-first code review unless the user
asks.
- Do not return the main walkthrough as Markdown unless the user explicitly asks
for text-only output.
- Do not hide uncertainty. If intent cannot be inferred from the PR, say what is
unclear and which issue, doc, or author question would resolve it.
- If the PR appears mechanically generated, still explain the source-of-truth
change that produced it.
