--- name: PR Walkthrough slug: pr-walkthrough category: AI Engineering description: PR Walkthrough generates a single-file HTML summary of a pull request. Use it when you need a scrollable page that explains the problem, approach, code changes, data flow, and trade-offs for reviewers. github: "https://github.com/kdlbs/kandev/tree/main/.agents/skills/pr-walkthrough" language: Go stars: 679 forks: 95 install: "npx degit https://github.com/kdlbs/kandev/tree/main/.agents/skills/pr-walkthrough ~/.claude/skills/pr-walkthrough" installs_to: ~/.claude/skills/pr-walkthrough source_path: .agents/skills/pr-walkthrough/SKILL.md collection_size: 25 category_size: 2451 collection_url: "https://dirskills.com/collections/kdlbs/kandev" added: 2026-08-23T05:21:09.830Z last_synced: 2026-08-23T05:21:09.830Z canonical_url: "https://dirskills.com/skills/pr-walkthrough" --- # PR Walkthrough PR Walkthrough generates a single-file HTML summary of a pull request. Use it when you need a scrollable page that explains the problem, approach, code changes, data flow, and trade-offs for reviewers. **Install:** ```bash npx degit https://github.com/kdlbs/kandev/tree/main/.agents/skills/pr-walkthrough ~/.claude/skills/pr-walkthrough ``` ## README # PR Walkthrough Generate one HTML file that orients a reviewer to a pull request. The page is a vertical, center-contained "story": the reviewer scrolls from the problem, through the architecture and the key code changes, to the data model and the trade-offs. This skill is **not** a code-review skill. Do not produce review findings, approve/request-changes verdicts, or a full critique. Explain the change so a reviewer understands it fast. The skill is provider-neutral. In Kandev CI, OpenCode runs it in read-only mode and a trusted workflow renders and publishes the resulting HTML. The skill never uploads files, changes a pull request, or handles hosting credentials. ## Output You do not write HTML. You write one JSON data file per PR, then run a renderer that builds the HTML: - Data file: `/pr-.json` - HTML page: `/pr-.html` `` is the directory for walkthrough files. The default is `docs/pr-walkthrough/`. The caller may set a different directory. If the host or a CI job gives you an exact path in your instruction, use that path and do not change it. Otherwise use the default and create it if it is missing. `` is the directory this skill lives in; use it for the `references/` paths in the commands below. For example, PR #12407 writes `pr-12407.json`, and the renderer writes `pr-12407.html`. Never write to a shared `index.html`, and never overwrite a walkthrough for a different PR. This keeps earlier walkthroughs on disk so several can be opened and compared at once. If a file for the same PR already exists, ask the user before overwriting it. The renderer is `references/build.py` (Python standard library only). It reads your JSON and the fixed shell at `references/shell.html`, then writes the HTML page. The shell holds all CSS and JS and stays the same for every PR. **Do not edit `shell.html` or `build.py`.** The renderer owns the parts that are easy to get wrong: it escapes all code, builds both the canvas and the list from one data source, places the canvas nodes, computes the GitHub file links, and fails loudly on a missing field. The renderer does not judge whether the content is true, clear, or useful. That is your job, and it is the whole job. A page that passes the build but has a vague `tldr`, a wrong `sig`, or a diagram that does not match the code is a failed walkthrough. Spend your effort on the quality of each JSON section, not on the mechanics the renderer already handles. Each section below states the bar it must meet. See `references/example.json` for a complete, working data file. Copy its shape. ### CI output mode When a trusted CI caller asks for machine-readable output, return exactly one block in this form and do not write any explanation before or after it: ```text {the complete walkthrough JSON object} ``` The caller extracts and validates this block before invoking the renderer. Keep the JSON object complete and use the PR number supplied by the caller. Do not include Markdown fences around the block. The HTML page loads from `file://` with no dev server. Runtime code (Tailwind, Mermaid, Marked, DOMPurify, Shiki) loads from exact-version CDN URLs owned by the fixed shell. Marked output is sanitized with DOMPurify before it goes into the page. The `build.py` step runs only at generation time; it adds no runtime dependency to the page. ## Writing style: Simplified Technical English (ASD-STE100) All prose in the page (captions, "why" text, trade-offs) must follow ASD-STE100: - One instruction or idea per sentence. Keep sentences short (procedure ≤ 20 words, description ≤ 25). - Use the active voice. Use the present tense where possible. - Use approved, simple words. Prefer one meaning per word (e.g. "use", not "utilize"; "start", not "initiate"). - Do not use synonyms for variety. Repeat the same word for the same thing. - Avoid slang, idioms, and long noun clusters (max three nouns in a row). - No emdashes. No emojis. Write plain, natural sentences. The goal is text that a non-native reviewer reads once and understands. ## Design constraints - **Vertical, center-contained.** Content sits in a single column, max width ~72rem, centered. The page reads top to bottom. - **Visual-heavy, low text.** Prefer bullet points, tables, diagrams, and code blocks over paragraphs. Each prose block is a few short sentences at most. - **Default dark theme**, with a working light-theme toggle in the topbar. Persist the choice in `localStorage`. - **Sticky topbar** with the PR title, in-page anchor links, and the theme toggle. - Syntax-highlighted code (Shiki, dual light/dark theme), with optional GitHub-style green/red diff lines. Diagrams with Mermaid. - **Code blocks link to GitHub.** Each code change links to its file in the PR diff, so the reviewer can jump to the source. - **Interactive code canvas.** The key code changes also show as a pan and zoom canvas. Each change is a node. Arrows show how the nodes interact. A click on a node opens a right-side detail panel with the full code. ## Workflow ### 1. Establish PR context Find the repository root, current branch, and comparison base. If a GitHub PR exists, read it and record the URL: ```bash gh pr view --json baseRefName,headRefName,title,body,url,state,files ``` If there is no PR, infer the base from the remote default: ```bash git symbolic-ref --short refs/remotes/origin/HEAD ``` **Always compare against the remote-tracking base, not the bare branch name.** A fresh checkout (this is the normal case in CI) has no local `master`, so `git diff master...HEAD` fails with `ambiguous argument 'master...HEAD': unknown revision`. Prefix the base branch from `gh pr view` with `origin/`. So for a PR based on `master`, `` is `origin/master`. Use that `` in every command below. Do not run the diff against the bare name first. Collect the diff and history: ```bash git --no-pager diff --stat ...HEAD git --no-pager diff --name-status ...HEAD git --no-pager log --oneline ..HEAD git --no-pager diff ...HEAD ``` ### 2. Understand the change against the full codebase Do not build the page from the diff alone. Read the full current version of each important changed file. Follow imports, call sites, types, state owners, and tests. Use the available repository search and read tools when the architecture is not obvious from filenames. The diff shows what changed; the surrounding code explains what it means. Read each file once and keep it in mind. Do not re-open the same file to copy one more excerpt; scroll back to what you already read. Copy code excerpts straight from the diff and the first read, not from a second `view` of the same file. Scale the page to the PR size. A small PR gets a short page with 2-3 code changes and one diagram. A large PR gets more sections, but never filler. If two blocks teach the same fact, merge them. ### 3. Plan the sections The JSON drives these sections. Keep only the ones that add value. The renderer draws a section when its key is present, and skips `architecture` and `data` when you omit them. The keys map to sections like this: 1. **Header / TL;DR** (`pr`) - the PR title, URL, base and head, file and line counts, and a one line `tldr`. The renderer builds the `

`, the badges, and the topbar. The topbar **Review split button** opens the GitHub review pane and copies `gh pr review --repo --approve`. It never approves on its own; the page holds no credentials. Set `pr.repo` to the `owner/repo` slug (for example `example-org/parcel-service`) so the copied command is correct. - Quality bar: `tldr` states, in one sentence, what the PR changes and why. A reader who reads only this line knows the point of the PR. Do not restate the title. Do not use vague words such as "improve" or "update" without the concrete change. 2. **Why and what** (`why`) - `why.problem` is one or two sentences. `why.what` is a bullet list of what the change does. - Quality bar: `why.problem` names the concrete problem the PR fixes, not the solution. `why.what` lists the real changes a reviewer will see in the diff, one per bullet, with no filler and no repeat of `tldr`. 3. **Architecture, end to end** (`architecture`) - one high-level Mermaid `flowchart` in `architecture.mermaid`, with a short `architecture.caption`. Omit the key for a PR that needs no diagram. Choose the flow direction from the first token: use `flowchart LR` (left to right) for a linear pipeline so it fills the full-width container and stays short, and `flowchart TD` (top to bottom) when the flow branches enough that `LR` would grow too wide. The renderer passes the direction through unchanged; it is your choice, not a fixed default. - Quality bar: the diagram shows the real components and the real flow the PR touches, with names that match the code. It is not a generic box diagram. Omit the section rather than draw a diagram that does not match the change. 4. **Key code changes** (`changes`, `edges`) - the code canvas plus a linear fallback list. See "Changes" below. Use 2-6 changes. - Quality bar: each change points at a real file and shows real code from the head commit. Each `why` says what the code does, not that it "was added". Each `sig` is the true signature. Each `edge` is a real call or data flow. A reviewer can trust the canvas as a map of the change. Show changed code as a diff so the reviewer sees what moved: use `patch` for a real hunk, or `diff: true` for an excerpt that is entirely new in this PR (it renders green). Use a plain `code` block only for context that the PR does not change. 5. **Data and storage** (`data`) - a Mermaid diagram in `data.mermaid`, or a `data.fields` table of `field`, `type`, and `note`. Keep only what the PR touches. Omit the key when the PR touches no data. - Quality bar: every field or entity is one the PR adds or changes. Types match the code. Omit the section for a PR that touches no data model. 6. **Risk** (`risk`) - a score from 1 to 10 (10 = highest risk) in `risk.score`, and short bullets in `risk.reasons`. See "Risk score" below. - Quality bar: the score follows from the reasons, and each reason is a real signal from this PR (blast radius, test coverage, rollback cost, data or contract change). Do not give a default middle score with generic reasons. 7. **Trade-offs and review notes** (`review`) - `review.tradeoffs` is a bullet list. `review.focus` is an ordered "where to look first" list. - Quality bar: `review.tradeoffs` names real choices the PR makes and what it gives up. `review.focus` orders the files or areas a reviewer should read first, most important first. Do not fill it with "check the tests" boilerplate. For a section the PR needs but the schema does not cover (for example a state-machine diagram or a config table), tell the user which section you cannot express and ask how to proceed. Do not edit `shell.html` to add it. #### Changes The renderer builds two views from one `changes[]` array: the pan and zoom canvas (primary) and a collapsed list (plain-text fallback). You never place a node or keep two views in sync; the renderer does both from each change object. Each entry in `changes[]` has these fields: - `title` - a short node title. Required. - `file` - the file path. Required. The renderer links it to the PR diff (see "GitHub file links"). - `why` - one short sentence on what the change does. Required. - `id` - a stable node id such as `"n1"`. Optional; the renderer assigns `n1`, `n2`, ... in order when you omit it. Set it when you reference the node in `edges`. - `sig` - one function or type signature shown on the compact node (for example `func (h *Handler) Get(...)`). Use the primary symbol the change adds or edits. Do not put a statement, an assignment, or two symbols here. Optional. - `group` - a boundary-box name (see below). Optional. - `blocks` - one or more code blocks. Required, at least one. Each block in `blocks[]` has: - `code` - the code excerpt. Required unless the block sets `patch` or renders Markdown. Write it as plain source; the renderer escapes it. Do not pre-escape `<`, `>`, or `&`. - `lang` - the Shiki language id (for example `go`, `typescript`, `bash`, `json`, `sql`). Required unless the block renders Markdown. - `label` - a short label above the block (for example `Handler`, `Get`). Optional. - `patch` - paste the raw hunk from `git diff` here to show a GitHub-style diff without marking lines by hand. Optional. The renderer drops the diff headers (`@@`, `---`, `+++`), keeps context lines, and records which lines are added or removed for you. Prefer `patch` over `code` + `diff` for any real diff; it removes the hand-marking a weak model gets wrong. Set `patch` or `code`, not both, and do not also set `diff`. - `diff` - set `true` to show a block as a GitHub-style diff. Optional; prefer `patch` for a real hunk. Two modes: (1) Hand-marked: put both old and new lines in `code`, then mark each changed line with a trailing comment, `// [!code --]` on a removed line and `// [!code ++]` on an added line. Use the language comment token (`#` for shell or Python, `--` for SQL). The renderer strips the marker and records the line. (2) All-added: set `diff: true` and mark no lines; the renderer treats every line as added, including blank lines, so a code excerpt that is entirely new in this PR renders green with no hand-marking and no untinted gaps. Use this for a new file or a new function. Removed lines tint red and added lines tint green. - `render` - set `"markdown"` to render the block as HTML (a table, list, or the PR comment the change produces) instead of a code excerpt. A Markdown block needs no `lang` and must not set `diff`. Use a Markdown table only when it shows data the prose does not. Do not restate the `why` or repeat the same cell value down a column; drop the block if the code excerpt already tells the reader enough. - `risk` - an optional risk heatmap for the block, so the reader sees where the risk sits while reading the code. It has: - `score` - a block risk score from 1 to 10. Optional. The renderer draws a colored chip (Low, Medium, High) beside the block label, using the same thresholds as the page risk score. - `reason` - one short sentence on why the block carries risk. Optional. Shown as the chip's hover tooltip. - `lines` - an optional list that tints specific lines. Each entry has `match` (a substring the renderer searches for in the block's code; the first line that contains it is flagged), `severity` (`low`, `medium`, or `high`; `low` draws no tint), and an optional `note` shown when the reader hovers the line. Match on a stable, distinctive substring, not a whole line, so the flag survives small edits. Add `risk` only where it earns its place: a terminal flag, an unbounded loop, an auth check. Do not flag every line. **Reserved tokens.** The renderer substitutes seven sentinels in the shell: `{{PR_TITLE}}`, `{{PR_URL}}`, `{{PR_FILES_URL}}`, `{{PR_NUMBER}}`, `{{REPO}}`, `{{RISK_SCORE}}`, and `{{CONTENT}}`. A code excerpt must not contain one of these tokens. If the real source holds one (this only happens when you walk through the walkthrough tool itself), the build fails with `unreplaced placeholder(s)`. Trim the excerpt so the token is not in it. `edges[]` connects nodes and draws labelled arrows. Each edge has `from`, `to` (both must match a change `id`), and a short `label` that names the interaction (for example `"writes row"`, `"reads rows"`). The renderer fails if an edge points at an unknown id. Draw an edge only for a real interaction: one node calls, reads, writes, or passes data to another. Prefer edges between neighbours. The renderer lays out groups as left-to-right columns, so an edge that skips a column draws a long arrow over the box between them and reads as clutter. Do not add an edge for a loose theme such as "same pattern" or "similar change"; leave those nodes unconnected. `group` draws a boundary box per service, job, or runtime the change touches. Give the same `group` string to every change that runs in that place; the renderer draws one box around them and lays out each group as a column. Add a `group` only when the change crosses a boundary (for example different backend services, or a CI job that writes to GitHub). Leave `group` off for a change that stays in one place. Use the canvas view when 3 or more changes interact. For a trivial PR with one or two isolated changes, still list them; the renderer keeps the list and the canvas holds few nodes. #### GitHub file links The renderer builds each file link for you. It anchors a file on the PR diff page by the SHA-256 of its path (`/files#diff-`). You do not compute the hash. Set `pr.url` correctly, and the links are right. For a rare case that needs a different target (for example a link to the file at the head commit, `/blob//`), set `file_url` on that change to override the default. #### Risk score Score the PR risk from 1 to 10, where 10 is the highest risk, in `risk.score`. The renderer sets the knob position and the level color (Low, Medium, High) from the number. Judge the score from real signals: blast radius, test coverage of the change, rollback cost, data or migration changes, and public contract changes. Give three short bullets in `risk.reasons` that justify the score. ### 4. Generate the page Write the data file to `/pr-.json` (see "Output" for how to resolve ``). Follow the shape in `references/example.json`. Use real file paths and real code from the head commit. Do not fabricate code. Keep the diagrams small: 5-12 nodes each. Then run the renderer (`` is the directory this skill lives in): ```bash python3 /references/build.py \ /pr-.json \ /pr-.html ``` The renderer validates the data and fails with a clear message on a missing field (for example `changes[0].file is required`). If it fails, fix the JSON and run it again. Do not edit the HTML by hand; the next run overwrites it. When it prints `wrote ...`, the page is built. The renderer has its own test suite. Run it after changing `build.py` to confirm the escaping, patch conversion, layout, and validation rules still hold: ```bash cd /references && python3 -m unittest test_build ``` ### 5. Validate The renderer already guarantees the mechanical parts: every code block is escaped, the canvas and the list match, no placeholder is left, and every edge points at a real node. Open the HTML in a browser and confirm the parts that need a live page: - Confirm the file opens from `file://` and needs no local server. - Confirm the theme toggle switches dark and light, and that code and diagrams stay readable in both. - Confirm every code block is highlighted and every Mermaid diagram renders. - Confirm the canvas spans the full browser width while the prose around it stays centered, and that the page has no horizontal scrollbar. - Confirm the canvas pans by dragging, the +/- buttons zoom in and out, and the mouse wheel scrolls the page (it does not zoom the canvas) even with the pointer over the canvas. - Confirm the Fit button frames all nodes and boundary boxes, and the Maximize button fills the viewport with an opaque background that hides the page content behind it, then re-fits. - Confirm a node click opens the right-side panel with the node title, file link, description, and highlighted code, even after a drag (the click hit-test uses the element under the pointer, not the drag capture target). - Confirm a node with more than one code block shows every block in the panel, each under its own label. - Confirm the panel opens wide enough to read the code, and that the reviewer can drag the panel left edge to resize it. - Confirm the panel close button, th