code-walkthrough

Code walkthrough

Produces one self-contained HTML file that reads like a GitHub PR page: a sidebar with colored filenames, a PR header that links to the real PR, an interactive model-relationship diagram, per-model field/method cards, views, wizards, security, and a Files-changed list. The look is fixed by bundled components; you only author the content.

How it works

assets/   octicons-sprite.html · walkthrough.css · walkthrough.js   ← the constant chrome (don't fork per-PR)
scripts/  build.mjs · i18n.mjs                                      ← deterministic renderer + chrome strings
examples/ pr-96 (backend: models/SQL view) · pr-93 (frontend: OWL/MVC view)  ← anonymized worked examples to copy

The examples are inputs only (*.content.mjs) — no built HTML ships, because it's a deterministic build artifact that would go stale. Preview one any time: node scripts/build.mjs examples/pr-96.content.mjs /tmp/preview.html.

Output language: pass lang: "fr" (or any table in scripts/i18n.mjs) in the content model to render the GitHub chrome in that language; authored prose is whatever you write. The bundled examples are anonymized synthetic data — safe to publish, fine to copy.

You write a content module (data only). build.mjs inlines the assets and renders it. Every walkthrough comes out structurally identical — that is the point. Never hand-write CSS, the sprite, or the JS into a walkthrough; if the look must change, edit the file in assets/ so all walkthroughs change together.

Quick start

cd .claude/skills/code-walkthrough
cp examples/pr-96.content.mjs /tmp/pr-NNN.content.mjs   # backend PR; use pr-93 for frontend/OWL
# ...edit /tmp/pr-NNN.content.mjs for the target PR...
node scripts/build.mjs /tmp/pr-NNN.content.mjs docs/walkthroughs/pr-NNN.html
open docs/walkthroughs/pr-NNN.html

Workflow

1. Gather the change. gh pr view <n> --json title,number,url,author,baseRefName,headRefName,additions,deletions,changedFiles,body,files (the files array carries per-file additions/deletions → the +N −M counts) and gh pr diff <n>. Read the new and changed files. Note the canonical PR url — the header links to it.
2. Extract the anatomy (see REFERENCE.md → "What to extract"): new models (and _auto=False SQL views), modified models with their new fields (compute, @api.depends, relations) and methods, new/changed views and their intent, wizards (transient models — say "none" explicitly if there are none and why), security (ir.model.access.csv rows + ir.rule records), and the why in plain language. For frontend-heavy PRs (OWL components, JS views, services, QWeb templates, Hoot tests) use REFERENCE.md → "Frontend / OWL PRs": same section skeleton, components instead of models — lean on the odoo-frontend and owl skills to read the code accurately.
3. Author the content module. Copy examples/pr-96.content.mjs. Fill pr, files[], and sections[] from the block catalog (REFERENCE.md). Put code in String.raw template literals — the builder HTML-escapes it.
4. Build & verify. Run build.mjs, open the HTML, click a diagram node, confirm sidebar filename colors (green = added, amber = modified) and the GitHub link.

Writing the "Why this PR exists" section

Lead with it and keep it concrete: a named persona, a before/after, the actual screen. Plain language, no jargon dump. Two-to-four sentences of setup, then the one architectural idea a reviewer should check the diff against, then what it deliberately doesn't do. Write deliverables in English. See REFERENCE.md for the full content schema and block catalog.