| name | pr-walkthrough |
| description | Generate an interactive visual walkthrough of any pull/merge request as a local HTML webapp. Produces a multi-slide presentation with SVG diagrams, annotated code, and architecture visuals. Pass a PR/MR URL and optional audience context (e.g. "assume I don't know Rust"). Use when the user says "walkthrough this PR", "explain this MR", "visual walkthrough", "PR presentation", or provides a PR/MR URL and asks for a walkthrough. |
PR Walkthrough
Generate a polished, interactive HTML slide deck that walks through a pull request or merge request. The output is a self-contained HTML file with no external dependencies that can be opened locally or served via a tunnel.
Input
The user provides a PR/MR URL and optionally additional context after it. Examples:
/skill:pr-walkthrough https://github.com/org/repo/pull/42
/skill:pr-walkthrough https://gitlab.example.com/team/project/-/merge_requests/13 assume i don't know zig or git internals
/skill:pr-walkthrough https://github.com/org/repo/pull/99 this is for a design review with the infra team, focus on the database migration risks
/skill:pr-walkthrough https://github.com/org/repo/pull/7 the audience is frontend engineers who haven't seen the backend before
The text after the URL is audience/framing context — use it to calibrate:
- What to explain vs. assume — e.g., "assume I don't know Rust" → add a background slide on relevant Rust concepts; no context → assume the reader knows the language and skip basics
- What to emphasize — e.g., "focus on perf implications" → heavier on benchmarks, data flow, and hot paths
- Who it's for — e.g., "for the security team" → emphasize auth, input validation, trust boundaries
If no extra context is given, assume the reader is a senior+ engineer familiar with the tech stack who wants a clear narrative of the change — skip language-level background and focus on the design and architecture.
Workflow
1. Gather PR Data
Determine the forge type and fetch PR metadata + diff:
GitLab (glab CLI):
glab mr view <number> --comments
glab mr diff <number>
GitHub (gh CLI):
gh pr view <number> --comments
gh pr diff <number>
If the user provides a full URL, parse out the MR/PR number and repo. If needed, set the repo context:
gh pr view <number> --repo owner/repo --comments
glab mr view <number> --repo owner/repo --comments
If CLI tools aren't available, try webfetch on the PR URL as a fallback.
2. Analyze the PR
Before generating, deeply understand:
- The problem — what existed before and why it was insufficient
- The solution — the core idea in one sentence
- The architecture — which layers/components are involved and how they connect
- The data flow — how data moves through the system, before and after
- The implementation — file-by-file, what changed and why
- Design decisions — tradeoffs made and alternatives rejected
- Results — benchmarks, metrics, or qualitative improvements
- Review findings — what reviewers flagged, what's approved vs. needs work
Read the actual source files in the repo when needed to understand context beyond the diff. Don't just rely on the diff — understand the surrounding code.
3. Plan the Slide Narrative
Structure slides as a narrative arc, not a file-by-file diff walkthrough. Typical structure:
| # | Slide | Purpose |
|---|
| 1 | Title + Impact | PR name, headline stats, one-sentence summary |
| 2 | Background | Domain concepts the reader needs. Explain jargon, protocols, data formats from first principles. Use tables and comparisons. |
| 3 | The Problem | What's broken/missing today. Diagrams showing the current flow with pain points highlighted. |
| 4 | The Solution | The core idea. Before/after diagrams. Design constraints and decisions. |
| 5 | Architecture | Where the code lives. Layer diagram showing all components touched and how they connect. |
| 6–8 | Implementation | Step-by-step code walkthrough of each major path (e.g., write path, read path). Annotated code snippets — NOT raw diffs. Flow diagrams with numbered steps. |
| 9 | Files & Storage | Summary of all files changed. Storage formats, schema changes, API changes. |
| 10 | Testing & Review | Test coverage, review findings, benchmark results, final verdict. |
Adapt the count and structure to the PR. Small PRs might need 4–5 slides. Large ones might need 12+. Every slide must earn its place — if it doesn't add understanding, merge it with another.
4. Generate the HTML
Write a single self-contained HTML file to walkthrough/index.html in the project root. Use the HTML template reference for the exact CSS framework, component library, and JavaScript.
Critical quality requirements:
- SVG diagrams for every architectural concept — data flow, layer stacks, before/after comparisons. Never describe what could be shown.
- Annotated code snippets — not raw diffs. Use syntax-highlighted pseudo-code or real code with added/removed line markers and comments explaining each change.
- Color system — green for improvements/additions, red for problems/removals, blue for neutral info, orange for warnings, purple for architecture elements.
- Stat cards for any quantitative results — transfer sizes, timing, counts.
- Callout boxes for key insights, warnings, and background knowledge.
- Responsive — works on mobile (cards stack vertically).
- Zero external dependencies — no CDN links, no Google Fonts, no JS libraries. Everything inline.
5. Serve (if requested)
If the user asks to host/serve/share the walkthrough:
cd walkthrough && python3 -m http.server 8787 &>/tmp/walkthrough-server.log &
echo "Server PID: $!"
sleep 1
cloudflared tunnel --url http://localhost:8787 &>/tmp/cloudflared-tunnel.log &
echo "Tunnel PID: $!"
sleep 5
grep -o 'https://[a-z0-9-]*\.trycloudflare\.com' /tmp/cloudflared-tunnel.log | head -1
Provide the URL and teardown command (kill <tunnel_pid> <server_pid>).
If cloudflared is not available, just open the HTML file directly: open walkthrough/index.html
Principles
- Show, don't tell. If something can be a diagram, make it a diagram.
- Calibrate to the audience. Use the user's context to decide what needs explanation. No context = assume they know the stack. "I don't know X" = teach X from first principles.
- Narrative over catalog. Tell a story: problem → insight → solution → proof. Don't just list files.
- Annotate, don't dump. Code snippets should have inline comments and colored markers. Never paste raw diff hunks.
- Earn every slide. Each slide should teach exactly one concept. If you're explaining two things, split. If a slide is filler, cut it.
- Accessible colors. Use the dark theme color system consistently. Green = good/new, red = bad/removed, blue = info, orange = caution, purple = architecture.
