How do I make my pull request easier to review?

Put a diagram of the change at the top of the description, before the prose. A reviewer's first question is which parts of the system this touches, and a picture answers it in seconds where a paragraph does not. Draw it before you open the pull request so you get to see it first.

Can I generate a diagram of my change locally?

Yes. The PR Lens CLI reads the diff between two refs with your own model key and writes a graph document, then renders it to self-contained SVGs. Run npx @coldtea/pr-lens-cli analyze --base origin/main, then render the document it writes.

Do I need an API key to draw my own change?

Only for the CLI's analyze command, which is the one that calls a model. If a coding agent is already open, the agent skill has it write the document itself and validate it against the contract, so there is no provider key in that path at all.

Should the diagram go in the description or a comment?

The description. A reviewer reads that first, and it is what they come back to. A comment works when you cannot edit the description, and it is where the PR Lens GitHub App posts, because the App does not own your description.

What should I look for in the diagram of my own change?

A component you did not mean to add, especially one sitting beside an existing component that does the same job. A struck-through card you did not mean to remove. An arrow that crosses a boundary it should not. And more than two or three connections worth emphasising, which usually means the branch is two changes.

Diagrams

Diagram the change before you open the pull request

Draw your change locally, look at it, fix what looks wrong, then open the pull request. Two commands with the CLI, or none if a coding agent is already open.

Ohans Emmanuel3 September 20267 min read

What a reviewer sees before they read anything. Draw it before you open the pull request, and you see it first.

Draw the change before you open the pull request, look at the picture, and fix whatever looks wrong while it is still cheap. It takes two commands. The reason to bother is in LinearB's 2026 benchmarks, built from 8.1 million pull requests across more than 4,800 organisations: AI-generated pull requests are accepted at 32.7% against 84.4% for manual ones. Some of that gap is code that deserved rejecting. A lot of it is changes that arrive unexplained, at a reviewer who would have to reconstruct the intent from the diff and decides not to start.

You are the only person who can see the picture early enough for it to change anything.

The two-command version

npx @coldtea/pr-lens-cli analyze --base origin/main
npx @coldtea/pr-lens-cli render .pr-lens/graph.json

analyze reads the diff and writes a graph document to .pr-lens/graph.json. render turns that document into self-contained light and dark SVGs, plus a manifest and drawn.graph.json, the document those pictures actually show.

Two details in analyze are worth knowing. The base is the merge base of the two refs, not the tip of the base branch, because a diff against the tip blames your branch for every change made on main since you forked. And the commit shas, the repository, the pull request number and the line counts are filled in from the repository itself; anything the model writes in those fields is discarded. A fact the model is free to restate is a fact that eventually disagrees with itself.

If you would rather look at the change on a page than at files on disk, npx @coldtea/pr-lens-cli canvas push puts it on prlens.dev as a canvas and prints the links to it. Which link you send to a person and which one you keep to yourself is in how to generate an architecture diagram from a git diff.

Everything lands in .pr-lens/, which the CLI adds to your .gitignore the first time it writes there. Treat the directory as scratch; generating a diagram from a git diff says why none of it is meant to be committed.

If a coding agent is already open

The CLI's analyze is the only path that spends a model key. If you have Claude Code, Cursor or OpenCode open, that key is redundant: the agent already understands the diff it just wrote.

npx skills add coldteadotai/pr-lens

The skill teaches the agent the loop rather than a command: read the diff with git diff --find-renames <base>...<head>, write the document, validate it, fix what the validator names, render. Every validation failure is a path into the document, so the loop closes without you in it.

There is an npm route too, if you would rather vendor it:

npm install --save-dev @coldtea/pr-lens-agent-skill
mkdir -p .claude/skills/pr-lens
cp -R node_modules/@coldtea/pr-lens-agent-skill/{SKILL.md,references} .claude/skills/pr-lens/

The same file works as a Cursor rule at .cursor/rules/pr-lens.mdc, and anything that reads an instructions file can be pointed at SKILL.md directly. It assumes a shell and npx and nothing else.

What to look for in your own diagram

This is the part that pays for the two commands, and it has nothing to do with the reviewer.

If the diagram of your own change surprises you, it was going to surprise your reviewer too.

Read the colour first. Green is new, amber is changed, red is gone, and the parts of the system that held still keep their ordinary outline. Most of what you learn arrives in that first pass: whether the amount of green matches the amount of new work you think you did, and whether the untouched components standing next to it are the ones you expected to be there.

Five things I look for, in order:

A green card sitting next to an existing card that does the same job. Code reuse blindness is one of the five red flags in GitHub's guide to reviewing agent pull requests, and it is almost invisible in a diff and obvious in a picture: two boxes, one lane, near-identical names.

A struck-through card you did not mean to delete. Removals are drawn ghosted and struck through rather than dropped, so a deletion you did not intend is a red box where you expected nothing.

An arrow that crosses a boundary it should not: a UI component reaching a data store directly, a worker calling a route. The lanes make the boundary visible, which is the point of choosing lanes that match a real boundary rather than the folder tree.

A lane you did not expect to be in the picture at all. If your change to the email path has put a card in the billing lane, either you learned something or the model did.

And more than two or three connections worth emphasising. One hero edge is the connection the change is really about. If you cannot pick one, the branch is probably two changes, and splitting it now costs less than splitting it after review.

If the change has a sequence to it, look at the data flow view as well, and follow it the way it plays: one step, one dot crossing one arrow. Say each step out loud as a sentence. This route publishes to that queue, that worker writes to that store. The step you cannot say out loud is the step you have not finished designing.

When one of these lands, the repair is smaller now than it will ever be again. A duplicate module is a delete and an import while nobody has read the branch, and a thread with three people in it afterwards. Fix it, redraw, and look again. The second picture is what tells you whether the change now matches the change you meant to make.

Put it in the description

A reviewer reads the description first and comes back to it. That is where the diagram belongs, above the prose.

With the GitHub CLI, the picture uploads alongside the pull request. Write the body with a Markdown image pointing at the local file, then pass the same path to --attach:

gh pr create --title "Batch broadcast sends" --body-file .pr-lens/body.md \
  --attach .pr-lens/overview-dark-4f9bd6c1.svg

Three rules apply. The reference has to be a Markdown image, ![alt](path); an HTML <img> or <picture> is left as written and the file lands at the bottom of the body instead. The alt text is what a reader without images gets, so say what the diagram shows in one line. And --attach is recent enough that the skill tells the agent to check gh --version before writing a body around it.

Attach the views a reviewer needs and leave the rest on disk. The top architecture view first, then a data flow if the change has a sequence worth following. A body with four diagrams reads worse than one with two.

Which model reads your diff

Gemini is the default and not a requirement. If your key belongs to another provider, or the model you want to draw with is running on your own laptop, the three request shapes and the rule about where analyze reads a key from are in how to generate an architecture diagram from a git diff. The diff goes to the provider you name and nowhere else; there is no PR Lens service in this path.

The one file worth committing

Everything in .pr-lens/ is disposable. There is one output that is not.

npx @coldtea/pr-lens-cli export .pr-lens/graph.json -o .github/pr-lens.map.json

export turns a pull-request document into a map of the system as it stands once the change has merged: the components the change deletes are dropped along with the edges hanging off them, the rest stops being annotated, and the result is stamped with the commit it reflects. Commit that and a repository has something to diff, and something to hand an agent that needs to know what the system looks like before it starts editing.

Nothing reads the map back into the pipeline. A committed map that overrode inference would be hand-maintained rot with merge conflicts attached.

When you forget

You will forget. That is what the GitHub App is for: pick your repositories once and every pull request opened in them is drawn, and redrawn on each push, as a single comment kept up to date in place.

Drawing it yourself first is still worth the two commands, because the App draws the change you shipped and this draws the change while you can still change it. The PR Lens CLI is the full command reference, and how to visualise a pull request as a diagram ranks every route including the ones that need no tooling at all.

Questions people ask

How do I make my pull request easier to review?: Put a diagram of the change at the top of the description, before the prose. A reviewer's first question is which parts of the system this touches, and a picture answers it in seconds where a paragraph does not. Draw it before you open the pull request so you get to see it first.
Can I generate a diagram of my change locally?: Yes. The PR Lens CLI reads the diff between two refs with your own model key and writes a graph document, then renders it to self-contained SVGs. Run npx @coldtea/pr-lens-cli analyze --base origin/main, then render the document it writes.
Do I need an API key to draw my own change?: Only for the CLI's analyze command, which is the one that calls a model. If a coding agent is already open, the agent skill has it write the document itself and validate it against the contract, so there is no provider key in that path at all.
Should the diagram go in the description or a comment?: The description. A reviewer reads that first, and it is what they come back to. A comment works when you cannot edit the description, and it is where the PR Lens GitHub App posts, because the App does not own your description.
What should I look for in the diagram of my own change?: A component you did not mean to add, especially one sitting beside an existing component that does the same job. A struck-through card you did not mean to remove. An arrow that crosses a boundary it should not. And more than two or three connections worth emphasising, which usually means the branch is two changes.

Sources

Keep reading

Turn it on

Install the App and every pull request in the repositories you pick gets drawn. Or hand the prompt to the agent you already have open.

Add to GitHub