PR Walkthrough

PR Walkthrough

Create a local static HTML/CSS/JavaScript walkthrough that orients a reviewer to the current branch's pull request as four separate interactive D3 views. The walkthrough should help the reviewer understand the affected code and the PR from four distinct views:

• System overview view: a concise standalone code overview for the subsystem touched by the PR. It should not feel like a graph. Present it as a small set of expanded component cards that give the reviewer just enough architectural context to get their bearings before reviewing the PR. Do not mention the PR, changed files, review comments, diff links, screenshots, specs, or implementation deltas in this view.
• Data flow graph: how state, data, events, requests, files, assets, or rendered output move through the changed system.
• Code dependency graph: which changed components depend on each other, where the major seams are, and which files are entry points versus leaf dependencies.
• User action graph: what the user does, what surface they interact with, and how that action flows through the implementation.

This skill is an experiment in canvas-based PR comprehension. Do not reproduce the slideshow format. Do not put all perspectives on one graph. Generate four separate canvas views that the user can toggle between, and provide a guided tour within each view so the site teaches the PR from start to finish. Scale the walkthrough to the PR size: a small PR should feel like a compact reviewer aid, not a comprehensive architecture document. This skill is not a code-review skill. Do not generate new review findings, approve/request-changes recommendations, or exhaustive critique. Use the full codebase at the PR/head commit, the PR diff, PR description, specs changed by the PR, and existing review comments from humans or agents to produce orientation maps that help a reviewer understand the change quickly.

Output

Create a self-contained site at:

• .warp/pr-walkthrough/index.html

The site must be loadable directly from the local filesystem with a file:// URL. Do not require a dev server, package install, bundler, or build step. Prefer one self-contained HTML file with inline CSS, inline JavaScript, and inline data. If splitting files is unavoidable, use only relative local files and avoid fetch() because browser restrictions can block local file reads. D3 should be loaded from a pinned official release on a reputable CDN. Use the helper script's default unless there is a concrete reason to change it:

• https://cdn.jsdelivr.net/npm/d3@7.9.0/dist/d3.min.js

Do not use unpinned latest URLs, unofficial builds, or dynamic package ranges. Do not show repeated D3 implementation disclaimers in the UI. Keep CDN/runtime details in validation logs or final caveats only when relevant. For reusable deterministic D3 rendering, prefer the helper script at scripts/d3_canvas_runtime.py. It emits Brandalf-aligned CSS, an inline runtime loader that defines the renderer before injecting the pinned D3 script, and a graph renderer with zoom, pan, graph switching, search, node details, fit-to-view, and guided tour controls. Use this helper rather than writing one-off D3 setup code in each generated walkthrough. The generated canvas must be treated as generated code that requires validation. Before reporting that a walkthrough is ready, run scripts/validate_d3_canvas.py against the generated HTML. If the canvas fails to initialize, D3 fails to load, required graphs are missing, tour controls do not work, nodes/edges do not render, or browser validation cannot be performed in an environment where it should be available, debug and regenerate before saying the walkthrough is ready. If a browser-capable environment is genuinely unavailable, report canvas rendering as unverified instead of ready.

Brand styling

Use the brandalf skill when generating or revising walkthrough visual design. Brandalf points to the hosted Warp brand source of truth; fetch and apply it before writing the HTML/CSS for the walkthrough. If the hosted brand source is unavailable, proceed with the fallback tokens below and report the caveat in the final response. Apply these Brandalf-derived defaults unless the fetched brand source says otherwise:

• Use a Warp dark surface: #121212 for the page background, #1e1e1d/#292929 for panels, and #faf9f6 or #ffffff for text.
• Use Warp pink accent #a43787 intentionally for active states, key links, focus rings, selected tour steps, and high-emphasis labels. Use secondary green #34895c, blue #2e5d9e, and purple #754dac as graph colors.
• Use Matter for UI/body text with DM Sans, system-ui, sans-serif fallback. Use Matter Mono for code, metadata, canvas labels, coordinates, file paths, and machine-oriented snippets with Roboto Mono, ui-monospace, monospace fallback.
• Keep copy truth-seeking, technical, concise, and verifiable. Avoid marketing superlatives and generic buzzwords.
• Prefer sharp, documentation-like containers with subtle borders. Use rounded corners only where they improve readability for cards, node callouts, tooltips, and buttons.

Recommended graph colors:

• System overview view: yellow #c0872a
• Data flow graph: green #34895c
• Code dependency graph: blue #2e5d9e
• User action graph: purple #754dac
• Active/focus/selected node: pink #a43787

Workflow

1. Establish PR context

Identify the repository root, current branch, and comparison base. Use the PR base branch if the current branch already has a GitHub PR, and record the PR URL for GitHub diff links:

gh pr view --json baseRefName,headRefName,title,body,url,state,reviewRequests,reviews,files

If there is no PR, infer the base branch from local repository conventions or the remote default branch:

git symbolic-ref --short refs/remotes/origin/HEAD

Then collect the review inputs:

git --no-pager diff --stat <base>...HEAD
git --no-pager diff --name-status <base>...HEAD
git --no-pager log --oneline <base>..HEAD
git --no-pager diff <base>...HEAD

Estimate PR size from changed lines, changed files, and conceptual breadth before building views. Default to the smallest useful walkthrough:

• Tiny PR: roughly 1 changed file or under 75 changed lines. Use 2-3 nodes/cards per view, 1-2 tour steps per view, and omit screenshots/review-discussion nodes unless they materially clarify behavior.
• Small PR: roughly under 250 changed lines or 1-3 changed files. Use 3-4 nodes/cards per view, 2-4 tour steps per view, and keep each node summary to 1 sentence plus at most 1 short detail.
• Medium PR: roughly 250-800 changed lines or several related files. Use 4-7 nodes per view only when each node teaches a distinct concept.
• Large PR: use the previous richer 5-12 node range only when the PR spans multiple subsystems, introduces new architecture, or has substantial review/spec context.

Do not inflate a small PR to fill the canvas. If two nodes would teach the same reviewer fact, merge them. If a view would duplicate another view, make it intentionally sparse rather than adding filler. Do not build walkthrough content from the diff alone. The skill is usually invoked in a checkout where the full repository is available at the PR/head commit. Use that checkout as architectural context:

• Read the full current versions of important changed files, not only their hunks.
• Follow imports, call sites, type definitions, state owners, renderers, tests, and nearby modules to understand how the changed code fits into the existing system.
• Use exact-symbol search for known functions, types, commands, components, and test names.
• Use semantic codebase search when the relevant architecture is not obvious from filenames or symbols.
• Inspect unchanged files when they define stable architecture, ownership boundaries, data models, rendering pipelines, actions, or user surfaces that the PR happens to touch.