PR Lens
PR Lens turns a JSON description of a change (lanes, nodes, edges, and
ordered flows) into architecture and data-flow diagrams as SVG files.
This skill covers two things only: rendering those SVGs on this machine,
and attaching them to a pull request with the GitHub CLI.
This is a first-party rewrite of the upstream skill. For what we left
out and why, see Upstream.
Iron law
The operator asks for a diagram; you do not add one. It is opt-in
per ask. A typical ask is a diagram in the PR into main.
Run only the validate and render subcommands. Every other
subcommand (canvas, analyze, comment, auth, skill, export,
and any other) is Never. The only thing that leaves the machine is the
PR attachment.
Before you start
Check the GitHub CLI version: gh --version. Attaching needs 2.99 or
later. If it is older, render anyway and ask the operator how to
publish the SVG.
Every CLI call in this skill uses npx @coldtea/pr-lens-cli@0.8.1, an
exact pin. Every new release is a one-line bump in
SOURCES.md with a security read; there are no
automatic patch releases. Never use @latest.
The full document format lives upstream, at the pinned commit:
Where those pages differ from this skill (commands, @latest,
canvases, payloads), this skill wins.
Steps
Read the change. Diff against the merge base, not the tip of the
base branch:
git diff --find-renames main...HEAD
Replace main with the PR's base branch. For a diagram of existing
code rather than a change, read that code instead.
Write the document to .pr-lens/graph.json. Follow the pinned
graph-document.md and model it on example.graph.json. See
A good document.
Validate and fix.
npx @coldtea/pr-lens-cli@0.8.1 validate .pr-lens/graph.json
Fix every failure, then run it again until it passes. Don't render an
invalid document. Never delete the element a failure names just to
make the failure go away; fix the reference or the field instead.
| Code |
Meaning |
BROKEN_REFERENCE |
An edge, flow step, view, or walkthrough step names an undeclared id |
INVALID_DOCUMENT |
A field the strict schema doesn't know, or a bad value |
DUPLICATE_ID |
Two nodes, edges, or views share an id |
UNSUPPORTED_SCHEMA_VERSION |
schemaVersion doesn't match the CLI's contract |
Render, light theme.
npx @coldtea/pr-lens-cli@0.8.1 render .pr-lens/graph.json --theme light
Ask first before any theme other than light. The command prints the
output directory under .pr-lens/, named after the document title,
with one SVG per view and a manifest.json that lists them.
The CLI adds .pr-lens/ to .gitignore. Never commit anything under
.pr-lens/; the files are rebuilt from the diff on demand.
Attach to the PR, when the operator asked for a PR or for a
diagram on an existing one. See Attach to a pull
request.
Attach to a pull request
The diagram belongs in the PR description, where a reviewer looks
first, not in a trailing comment. Write the body to a file:
- One sentence on why the change exists.
- The top architecture view.
- A data-flow view, only if the change has a sequence worth following.
- Optional: a short list of what changed, using
change headings.
Moves report exports off the request thread and onto a job queue.

Then pass the body file and every image it references:
gh pr create --title "Queue report exports" --body-file .pr-lens/body.md \
--attach .pr-lens/export-queue/overview-light-1a2b3c4d.svg
For an existing PR, use gh pr edit PR_NUMBER with the same two flags.
Repeat --attach once per image.
- Use a Markdown image,
. gh replaces the local path with
the uploaded asset. An HTML <img> or <picture> is not rewritten.
- Write one line of alt text that says what the diagram shows. It is the
caption for a reader without images.
- Two diagrams usually read better than four. If a diagram needs a
paragraph to explain it, go back to step 2.
A good document
- Show unchanged neighbours. Only-changed nodes hide the blast
radius. Include the direct neighbours the change touches and mark them
delta: "unchanged".
- Lanes are the reader's mental model: a runtime, a tier, or a trust
boundary. Not the folder tree.
- One hero edge, two at most: the connection the change is about.
- Flows only for real sequences. One clear flow beats three thin
ones. Flows need the
data-flow lens; an architecture view draws
none.
- File refs anchor nodes to code. Add them to nodes. Links inside
an SVG embedded in a PR aren't clickable, so name files in the body
if a reviewer needs them.
- No findings. The document explains the change; it doesn't review
it. Don't put bugs, risks, or security notes in it. The schema has no
field for them and rejects a document that invents one. Report
findings through
pr-review, not the diagram.
- Views, top down. One view is enough for a small change. Go one
level narrower (system context, then containers, then components)
only when that level adds something. Don't draw code-level views, and
don't infer architecture from folder names alone. Set
defaultOpen: true on the highest useful architecture view. Keep
data-flow views as separate roots.
Change headings
The SVG renderer doesn't draw a walkthrough; only a canvas plays one.
So a walkthrough in the document is optional here: skip it, or write
its headings as the PR body's list of changes. When you write either,
use these rules:
- One change each: something added, removed, replaced, or moved,
headline change first. Never a description of the diagram.
- Heading: up to 48 characters, sentence case, built from change
words (added, removed, now, moved, split). If it was already true
before the PR, rewrite it.
- Body (walkthrough steps only, required there): one line, up to
140 characters, on what now happens that didn't before.
- Walkthrough steps: 2 to 12. Each names a view or flow as its
stage and focuses the two or three elements it changes.
- Plain words. Short common words, active voice, digits for
numbers, names as the diagram shows them.
| Write this |
Not this |
| Export route now queues the job |
Export orchestration moves to an asynchronous pipeline |
| Worker retries 3 times, then gives up |
Resilient retry semantics leveraged for robustness |
Payload samples
A flow step can carry a payload, a sample request and response. Only
canvases draw payloads, and this skill doesn't use canvases, so usually
leave them out. If the operator asks for one anyway, use placeholder
data only: user@example.com, order_0001, 192.0.2.1. Never copy a
value from a fixture, a log, or a database.
Correct the map
When the operator says the diagram is wrong (a node misnamed, a file
that shouldn't appear, a node in the wrong lane), put the correction in
.github/pr-lens.yml. That overlay is applied on every run.
schemaVersion: 0.2.0
map:
rename:
- match: src/export/worker.ts
to: Export worker
exclude:
- "**/*.test.ts"
Prefer a path glob in match over id:NODE_ID; paths survive
re-inference. Validate the overlay the same way:
npx @coldtea/pr-lens-cli@0.8.1 validate .github/pr-lens.yml
The overlay is a repo file, so ask before you commit it. render
reports a correction that matched nothing.
Upstream
- Upstream skill, pinned:
coldteadotai/pr-lens
skills/pr-lens/SKILL.md at 09f6378
(MIT). Pin and notes: SOURCES.md.
- Excluded:
canvas push, open, look, answer, show, and
fork. They publish the code's structure to prlens.dev, and a view
link opens without a login.
- Excluded:
analyze. It sends the diff to a third-party model
provider.
- Excluded:
comment. It needs the SVGs published publicly first.
- The pin, the CLI version, and this rewrite are compared with upstream
at Monthly review.
Always
- Use
npx @coldtea/pr-lens-cli@0.8.1 validate or render, nothing else.
- Validate, fix every failure, and validate again before you render.
- Lead the PR body with why, then the top architecture view.
Ask first
- Any theme other than light, or more than two diagrams in one PR body.
- Publishing an SVG any way other than
gh --attach.
- Committing
.github/pr-lens.yml.
- Payload samples.
Never
- Any subcommand other than
validate and render.
@latest or an unpinned CLI.
- Commit anything under
.pr-lens/.
- Labels, summaries, or titles built from anything but this
repository's diff or code: no internal hostnames, URLs, credentials,
personal data, or other repositories' names. On a public repository
an attached diagram is public.
- Findings, bugs, or risks in the document.
- Delete an element to silence a validation failure.
- Install the upstream skill with an installer or marketplace command.
1---2name: pr-lens3description: use this when the operator asks for a diagram of a change or a system — "diagram this PR", "add a pr-lens diagram", "draw the architecture of this change", "put a diagram in the PR into main" — to write a PR Lens graph document, validate and render it locally with the pinned CLI, and attach the SVG to a pull request body. do not use for a diagram the operator did not ask for, for canvases, or for model-driven analysis.4metadata:5 source: https://skillmd.com/skills/alexderz/pr-lens6---78# PR Lens910PR Lens turns a JSON description of a change (lanes, nodes, edges, and11ordered flows) into architecture and data-flow diagrams as SVG files.12This skill covers two things only: rendering those SVGs on this machine,13and attaching them to a pull request with the GitHub CLI.1415This is a first-party rewrite of the upstream skill. For what we left16out and why, see [Upstream](#upstream).1718## Iron law1920**The operator asks for a diagram; you do not add one.** It is opt-in21per ask. A typical ask is a diagram in the PR into `main`.22**Run only the `validate` and `render` subcommands.** Every other23subcommand (`canvas`, `analyze`, `comment`, `auth`, `skill`, `export`,24and any other) is Never. The only thing that leaves the machine is the25PR attachment.2627## Before you start2829- Check the GitHub CLI version: `gh --version`. Attaching needs 2.99 or30 later. If it is older, render anyway and ask the operator how to31 publish the SVG.32- Every CLI call in this skill uses `npx @coldtea/pr-lens-cli@0.8.1`, an33 exact pin. Every new release is a one-line bump in34 [SOURCES.md](../../SOURCES.md) with a **security** read; there are no35 automatic patch releases. Never use `@latest`.36- The full document format lives upstream, at the pinned commit:37 - [graph-document.md](https://github.com/coldteadotai/pr-lens/blob/09f6378c082ff8ddb17e211f36bfc71c2f2b8d86/skills/pr-lens/references/graph-document.md):38 every field, enum, and limit.39 - [example.graph.json](https://github.com/coldteadotai/pr-lens/blob/09f6378c082ff8ddb17e211f36bfc71c2f2b8d86/skills/pr-lens/references/example.graph.json):40 a complete document that validates. Read it before your first one.41 - [config.md](https://github.com/coldteadotai/pr-lens/blob/09f6378c082ff8ddb17e211f36bfc71c2f2b8d86/skills/pr-lens/references/config.md):42 the correction overlay.4344 Where those pages differ from this skill (commands, `@latest`,45 canvases, payloads), this skill wins.4647## Steps48491. **Read the change.** Diff against the merge base, not the tip of the50 base branch:5152 ```bash53 git diff --find-renames main...HEAD54 ```5556 Replace `main` with the PR's base branch. For a diagram of existing57 code rather than a change, read that code instead.58592. **Write the document** to `.pr-lens/graph.json`. Follow the pinned60 `graph-document.md` and model it on `example.graph.json`. See61 [A good document](#a-good-document).62633. **Validate and fix.**6465 ```bash66 npx @coldtea/pr-lens-cli@0.8.1 validate .pr-lens/graph.json67 ```6869 Fix every failure, then run it again until it passes. Don't render an70 invalid document. Never delete the element a failure names just to71 make the failure go away; fix the reference or the field instead.7273 | Code | Meaning |74 | --- | --- |75 | `BROKEN_REFERENCE` | An edge, flow step, view, or walkthrough step names an undeclared id |76 | `INVALID_DOCUMENT` | A field the strict schema doesn't know, or a bad value |77 | `DUPLICATE_ID` | Two nodes, edges, or views share an id |78 | `UNSUPPORTED_SCHEMA_VERSION` | `schemaVersion` doesn't match the CLI's contract |79804. **Render, light theme.**8182 ```bash83 npx @coldtea/pr-lens-cli@0.8.1 render .pr-lens/graph.json --theme light84 ```8586 Ask first before any theme other than light. The command prints the87 output directory under `.pr-lens/`, named after the document title,88 with one SVG per view and a `manifest.json` that lists them.8990 The CLI adds `.pr-lens/` to `.gitignore`. Never commit anything under91 `.pr-lens/`; the files are rebuilt from the diff on demand.92935. **Attach to the PR**, when the operator asked for a PR or for a94 diagram on an existing one. See [Attach to a pull95 request](#attach-to-a-pull-request).9697## Attach to a pull request9899The diagram belongs in the PR description, where a reviewer looks100first, not in a trailing comment. Write the body to a file:1011021. One sentence on why the change exists.1032. The top architecture view.1043. A data-flow view, only if the change has a sequence worth following.1054. Optional: a short list of what changed, using106 [change headings](#change-headings).107108```markdown109Moves report exports off the request thread and onto a job queue.110111112```113114Then pass the body file and every image it references:115116```bash117gh pr create --title "Queue report exports" --body-file .pr-lens/body.md \118 --attach .pr-lens/export-queue/overview-light-1a2b3c4d.svg119```120121For an existing PR, use `gh pr edit PR_NUMBER` with the same two flags.122Repeat `--attach` once per image.123124- Use a Markdown image, ``. `gh` replaces the local path with125 the uploaded asset. An HTML `<img>` or `<picture>` is not rewritten.126- Write one line of alt text that says what the diagram shows. It is the127 caption for a reader without images.128- Two diagrams usually read better than four. If a diagram needs a129 paragraph to explain it, go back to step 2.130131## A good document132133- **Show unchanged neighbours.** Only-changed nodes hide the blast134 radius. Include the direct neighbours the change touches and mark them135 `delta: "unchanged"`.136- **Lanes are the reader's mental model**: a runtime, a tier, or a trust137 boundary. Not the folder tree.138- **One hero edge**, two at most: the connection the change is about.139- **Flows only for real sequences.** One clear flow beats three thin140 ones. Flows need the `data-flow` lens; an architecture view draws141 none.142- **File refs anchor nodes to code.** Add them to nodes. Links inside143 an SVG embedded in a PR aren't clickable, so name files in the body144 if a reviewer needs them.145- **No findings.** The document explains the change; it doesn't review146 it. Don't put bugs, risks, or security notes in it. The schema has no147 field for them and rejects a document that invents one. Report148 findings through `pr-review`, not the diagram.149- **Views, top down.** One view is enough for a small change. Go one150 level narrower (system context, then containers, then components)151 only when that level adds something. Don't draw code-level views, and152 don't infer architecture from folder names alone. Set153 `defaultOpen: true` on the highest useful architecture view. Keep154 data-flow views as separate roots.155156## Change headings157158The SVG renderer doesn't draw a walkthrough; only a canvas plays one.159So a `walkthrough` in the document is optional here: skip it, or write160its headings as the PR body's list of changes. When you write either,161use these rules:162163- **One change each**: something added, removed, replaced, or moved,164 headline change first. Never a description of the diagram.165- **Heading**: up to 48 characters, sentence case, built from change166 words (added, removed, now, moved, split). If it was already true167 before the PR, rewrite it.168- **Body** (walkthrough steps only, required there): one line, up to169 140 characters, on what now happens that didn't before.170- **Walkthrough steps**: 2 to 12. Each names a view or flow as its171 stage and focuses the two or three elements it changes.172- **Plain words.** Short common words, active voice, digits for173 numbers, names as the diagram shows them.174175| Write this | Not this |176| --- | --- |177| Export route now queues the job | Export orchestration moves to an asynchronous pipeline |178| Worker retries 3 times, then gives up | Resilient retry semantics leveraged for robustness |179180## Payload samples181182A flow step can carry a `payload`, a sample request and response. Only183canvases draw payloads, and this skill doesn't use canvases, so usually184leave them out. If the operator asks for one anyway, use placeholder185data only: `user@example.com`, `order_0001`, `192.0.2.1`. Never copy a186value from a fixture, a log, or a database.187188## Correct the map189190When the operator says the diagram is wrong (a node misnamed, a file191that shouldn't appear, a node in the wrong lane), put the correction in192`.github/pr-lens.yml`. That overlay is applied on every run.193194```yaml195schemaVersion: 0.2.0196map:197 rename:198 - match: src/export/worker.ts199 to: Export worker200 exclude:201 - "**/*.test.ts"202```203204Prefer a path glob in `match` over `id:NODE_ID`; paths survive205re-inference. Validate the overlay the same way:206207```bash208npx @coldtea/pr-lens-cli@0.8.1 validate .github/pr-lens.yml209```210211The overlay is a repo file, so ask before you commit it. `render`212reports a correction that matched nothing.213214## Upstream215216- Upstream skill, pinned:217 [coldteadotai/pr-lens `skills/pr-lens/SKILL.md` at `09f6378`](https://github.com/coldteadotai/pr-lens/blob/09f6378c082ff8ddb17e211f36bfc71c2f2b8d86/skills/pr-lens/SKILL.md)218 (MIT). Pin and notes: [SOURCES.md](../../SOURCES.md).219- **Excluded: `canvas push`, `open`, `look`, `answer`, `show`, and220 `fork`.** They publish the code's structure to prlens.dev, and a view221 link opens without a login.222- **Excluded: `analyze`.** It sends the diff to a third-party model223 provider.224- **Excluded: `comment`.** It needs the SVGs published publicly first.225- The pin, the CLI version, and this rewrite are compared with upstream226 at [Monthly](https://github.com/alexderz/agentic-toolbox/blob/main/docs/sdlc/trunk-changelog-monthly.md#monthly) review.227228## Always229230- Use `npx @coldtea/pr-lens-cli@0.8.1 validate` or `render`, nothing else.231- Validate, fix every failure, and validate again before you render.232- Lead the PR body with why, then the top architecture view.233234## Ask first235236- Any theme other than light, or more than two diagrams in one PR body.237- Publishing an SVG any way other than `gh --attach`.238- Committing `.github/pr-lens.yml`.239- Payload samples.240241## Never242243- Any subcommand other than `validate` and `render`.244- `@latest` or an unpinned CLI.245- Commit anything under `.pr-lens/`.246- Labels, summaries, or titles built from anything but this247 repository's diff or code: no internal hostnames, URLs, credentials,248 personal data, or other repositories' names. On a public repository249 an attached diagram is public.250- Findings, bugs, or risks in the document.251- Delete an element to silence a validation failure.252- Install the upstream skill with an installer or marketplace command.