Error in user YAML: (<unknown>): did not find expected key while parsing a block mapping at line 1 column 1
---
description: Simple, technical, high-fidelity tl;dr of a GitHub PR — grounded in the real diff, jargon explained inline.
argument-hint: '[PR URL | PR number | (empty = current branch's PR)]'
---
Produce a short, plain-English-but-technically-precise summary of a PR. Optimize for a reader who is smart but was not in the room: every jargon term or acronym gets a quick inline gloss the first time it appears, but nothing is dumbed down or made less accurate.
The core discipline: ground the summary in the real diff, not just the PR description. PR descriptions (especially AI-authored ones) can be stale, aspirational, or wrong. Read the actual commits/diff and treat the written description as a claim to verify, not a source of truth.
Resolve the PR.- Argument is a full URL → use it directly.
- Argument is a bare number → needs a
--repo
; infer from the current directory's git remote (gh repo view --json nameWithOwner
) if not stated. - No argument → resolve the PR for the current branch (
gh pr view --json ...
with no ref uses the current branch).
Pull real data, not just the description:gh pr view <ref> --repo <repo> --json title,body,commits,url,additions,deletions,files
gh pr diff <ref> --repo <repo>
— read enough of the actual diff to independently confirm what changed. For large diffs, prioritize the files with the biggest change or that match the PR title's claim.- If the description references specific functions/endpoints/behavior, spot-check them in the diff or via
gh api
/file reads. Note it if the description and the diff disagree.
Write the tl;dr. Structure:One-line headline— what changed and why, in plain English, no unexplained jargon.** What changed**— 2-5 bullets, technically specific (real file/function/endpoint names), each one fact anchored in the diff/commits you actually read.Why— the motivating problem or context, in plain terms. Skip if the headline already covers it.** Jargon glosses**— any acronym or term of art (e.g. "fan-out", "dedupe queue", "idempotent") gets a short parenthetical the first time it's used:fan-out (one event triggering many downstream operations)
. Don't gloss terms a general engineer already knows (e.g. "endpoint", "lambda").Worth flagging— only if genuinely notable: blast radius, missing test coverage, feature-flag/rollback story, or a discrepancy between the PR description and the real diff. Omit this section entirely if there's nothing worth flagging — don't pad.
Constraints:- Default to under ~150 words total. Scale up only if the PR is large/multi-concern — never pad a small PR to look thorough.
- Never invent behavior not visible in the diff/commits.
- No restating the PR's own checklist/test-plan verbatim — synthesize, don't transcribe.
- No headers-for-headers'-sake on a small PR; a tiny one-file fix can just be 2-3 sentences.