DEV Community: YS Lee

A PR walkthrough needs evidence between the steps

YS Lee — Tue, 22 Sep 2026 13:47:52 +0000

A suggestion on GitHub changed what I wanted to improve next in PR Tour, the open-source skill I’m building for Codex and Claude Code.

The guide could show every changed file and cite valid source lines, yet still leave out the connection between two steps. An unchanged callback or queue might be the part a reader actually needs.

imMamdouhaboammar suggested making the transition itself explicit. That led to the main change in v0.7.0: a reader can now inspect the source behind a step-to-step explanation.

Give the next step a reason and some evidence

The existing next text still explains why the guide moves on. An optional transition adds the destination and the basis of that explanation:

{
  "next": "The response receives the WebSocket send method. Follow that callback to state handling.",
  "transition": {
    "to": "response-state",
    "basis": "source",
    "evidence": [
      {
        "path": "starlette/websockets.py",
        "side": "right",
        "start": 207,
        "end": 209,
        "text": "The response receives the current WebSocket send method."
      }
    ]
  }
}

This fragment comes from the pinned Starlette example. The full example adds the callback implementation and destination branch as well.

The builder reads the cited ranges from Git. right means the pinned head; left means the merge base. The source can come from an unchanged file, because the connection often lives outside the diff.

In the HTML, View connection evidence expands those excerpts with line numbers, syntax colors, and links to the pinned source. The excerpts are bundled into the same file and remain readable offline.

Show what the explanation has not established

There are three authored categories:

Source cited: the explanation includes source excerpts.
Includes inference: the author must state what remains unverified.
Reading order: the move helps understanding, such as moving from implementation to tests.

I used “Source cited” because a valid source range does not prove a call relationship. The builder checks the destination step, source identity, and ranges. The agent still authors the explanation.

The queue handoff in the demo is an example of that distinction. It shows the send callback, queue insertion, queue retrieval, and session entry. It also says that the full TestClient wrapping and session-creation path is not included, so the interpretation still contains an inference. It makes no claim about a real network server’s transport.

The example has seven connections: three source-cited, one including inference, and three reading-order moves. Those counts describe the guide’s annotations; they are not an execution-path coverage score.

Older manifests still build. Adding this information to an old guide requires authoring the transitions and regenerating the HTML; a rebuild alone cannot supply the missing reasoning.

The next piece of feedback was about space

Once source excerpts were inside the explanation pane, the three-column layout felt cramped.

The two desktop dividers are now draggable. Moving one resizes its adjacent panes, with minimum widths so a pane does not disappear. Widths follow the guide and code when their order is switched, and the browser remembers them when storage is available. Double-click a divider to reset; keyboard users can focus it and use arrow keys or Enter. Mobile keeps its Guide / Code tabs.

I checked the update in Chromium and WebKit, including offline excerpts, pane resizing, mobile navigation, and existing review-comment behavior. Comment imports still require the same PR snapshot and exact source.

The WebKit checks also caught a race when two tabs saved comments at once: serializing localStorage writes with Web Locks did not always make the next tab’s read current. Comment saves now read, merge, and write in one IndexedDB transaction. Existing localStorage comments are imported without deleting the old copy, and the JSON backup remains available when browser storage is blocked.

Try the English demo · Source and installation

If you try it, I’d like to know where the reading order still loses you. Does the cited code explain the jump, and is it clear which part remains an inference?

Written with AI assistance from Codex.

Adding portable review comments to a single HTML file

YS Lee — Mon, 21 Sep 2026 08:48:40 +0000

Someone trying PR Tour, the pull request walkthrough tool I'm building, suggested a useful next step: let readers comment on the code, then copy the comments and their source lines into an AI coding tool.

The guide already showed real diffs, explanations, and clickable definitions in one standalone HTML file. But when a reader had a question, they still had to carry it elsewhere and explain which part of the code they meant.

PR Tour 0.6.0 now lets readers select a line or range, write a comment, and copy or download JSON containing the feedback and its source context. The same JSON can be imported back into a matching guide.

Here is the comment editor at a mobile viewport size, using the public Starlette PR #2041 demo. The question is an example comment, not feedback submitted to Starlette.

A line number needs a version

“Check line 211” is incomplete context. It could refer to the old file, the new file, or a newer checkout where line 211 has moved.

The export includes the PR and repository URLs, pinned head/base/merge-base commits, and a record for each comment:

A stable comment ID.
The file path, diff side, and commit for that side.
The inclusive start and end lines.
The exact selected source text, without diff markers.
The comment body and timestamps.

For a renamed file, a comment on the old side keeps the old path. Selected source is exported as text; syntax colors and clickable definition markup stay in the UI.

The Copy for AI button copies this JSON. It does not call a model or publish a GitHub review. Whoever uses the export still needs to check the pinned commit against their checkout and evaluate the comment against the code.

Browser storage is convenient; JSON makes it portable

Saved comments stay in browser storage, grouped by PR and source snapshot. Reloading the same guide can restore them, and changing the reading step or UI language does not create a different comment collection.

That storage has limits. Clearing browser data removes it, another device does not have it, and a local-file or embedded viewer may restrict it. The interface shows storage failures and keeps current-session comments available for export.

Download JSON provides a backup that the reader can carry to another browser. The HTML itself is unchanged, so sharing only the HTML does not share the comments.

Import is deliberately strict. It checks the PR, repository, pinned commits, file side, line range, and exact selected source before applying anything. One invalid record rejects the whole file. There is no attempt to guess where an old comment belongs in a newer revision.

Before import, a preview shows additions, duplicates, and conflicting edits. Existing comments win by default; replacing conflicts requires an explicit choice. Re-importing an unchanged comment with the same ID skips it. Different IDs remain separate, and imports do not propagate deletions.

The bug hiding behind a second tab

During pre-release review, we caught a problem in the first storage implementation. Each tab loaded the comment collection once and later saved the whole collection back.

Consider two tabs that both start with no comments:

Tab A adds a comment and saves [A].
Tab B, still holding its original empty collection, adds another and saves [B].
A's comment disappears from storage.

No network or database was involved. The stale copy in the second tab was enough.

The fix uses Web Locks, when available, to serialize saves for that snapshot. Inside the lock, a save reads the latest stored collection and merges the current tab's additions, edits, and deletions by ID. Unrelated comments survive.

If another tab has changed the same comment incompatibly, the save preserves the stored version, keeps the current tab's edits in memory, and asks the reader to download JSON before reloading.

Without Web Locks, the fallback refuses a save when it detects that storage changed. That fallback does not guarantee atomic writes from simultaneously saving tabs. Open comment lists also do not live-sync across tabs.

Keeping the code reachable on a phone-sized screen

The other recent feedback was about navigation: moving to the next explanation left too much scrolling to reach the relevant code.

The mobile Code view now has previous/next controls that follow individual code notes across reading steps and scroll to their lines. It stays in the Code tab. An expanded reading view makes more room for the diff, and the comment editor opens as a bottom sheet with larger line-selection targets.

I checked these flows at mobile viewport sizes in Chromium and WebKit, including export/import, offline files, reload persistence, and the two-tab save cases. I have not verified them on physical phones or inside Orca's artifact viewer yet.

The biggest design change was deciding what travels with a comment: enough source context to identify what the reader saw, and a portable copy the reader can keep outside browser storage.

You can try the English demo, browse the source and installation instructions, or read the JSON format and storage behavior. I'm the creator of PR Tour. Existing guides need to be regenerated with the updated skill to get these features.

Written with AI assistance from Codex.

Adding syntax colors without changing the diff

YS Lee — Fri, 18 Sep 2026 07:28:48 +0000

Someone trying the pull request reading guide I'm building pointed out that the code was hard to read because most of it appeared in one color.

The diff already had green backgrounds for additions, red for deletions, line numbers, and links to selected definitions. Those cues showed where the changes were. Keywords, strings, and comments still looked much alike.

I added syntax highlighting to the diff and the definition previews. Here is the same method before and after the change. The example code is from Starlette PR #2041.

Before

After

The added-line backgrounds stay green. Syntax colors provide another set of cues within each line.

Adding those colors also meant preserving the source and the clickable names. Three implementation details mattered:

Highlight the old and new files separately. A diff mixes deleted and added lines, but those lines belong to different versions of the file. Parsing each complete snapshot, including collapsed context, keeps a multiline string on one side from affecting the other side.
Keep the original text. The renderer uses highlight.js to obtain token ranges, checks that its decoded text matches the source, and applies those ranges to the original text. It does not insert the highlighter's HTML directly into the page.
Keep reading possible when highlighting fails. Unknown file types, lexer errors, or a text mismatch fall back to plain code. A color feature should not prevent the diff from rendering.

Definition links use character offsets in the same source text, so preserving whitespace and Unicode positions matters too. The regression tests cover multiline strings, collapsed context, renamed files, and text containing emoji or HTML-like characters.

The screenshots show a presentation change, not a measured improvement in review speed. What the feedback exposed was a gap in the original UI: marking changed lines did not give readers the familiar syntax cues they expected inside those lines.

Written with AI assistance from Codex.

Why a PR walkthrough can pass validation and still be hard to read

YS Lee — Mon, 14 Sep 2026 05:06:39 +0000

I made an HTML guide for reading pull requests. When I shared it with coworkers, the visual feedback was encouraging, but I still felt that parts were hard to follow. One person wanted to see the explanation before the code pane, which led to a layout switch.

That feedback points to a limit of validation: source references can all be valid while the reader still lacks the context needed to understand a change.

The implementation discussed here is my project, PR Tour. A coding agent writes the reading order, explanations, and definition mappings into a manifest. A Python builder reads the repository and produces the HTML. The builder can check the source material much more directly than it can check the explanation.

Make every excerpt belong to a snapshot

The manifest records the PR URL and base and head commits. The builder resolves the commits, computes their merge base, and collects the changed files between that merge base and the head. The left and right sides of the guide come from those snapshots.

This makes a reference reproducible. It also imposes a limit: if the PR changes afterward, the saved HTML still describes the old snapshot. A working link to a PR does not make the embedded code current.

The useful invariant is that an excerpt and its line numbers refer to the same source revision. Whether the explanation correctly describes that revision remains a separate review question.

Reconstruct both sides of the diff

A normal diff omits unchanged regions. For supported text files, the builder adds that context back as expandable rows, then checks the result against the source from Git.

It checks two properties on each side:

The line numbers form the complete expected sequence.
The reconstructed line text equals the original source text.

Checking the numbering alone would leave room for incorrect text at a valid position. Checking text alone would miss errors in the line labels that notes rely on. Both are needed for a trustworthy source view.

The builder also requires every changed file to appear in a reading step, including files it cannot render as a text diff. Binary and non-UTF-8 files get a notice directing the reader to GitHub.

That is file coverage, not explanation coverage. A step can mention a file and still omit an important failure path. The same file can also appear in multiple steps, because following a behavior may require returning to it later.

Validate link placement without claiming symbol resolution

Definition previews use authored mappings. The builder verifies that the target exists, its source range is valid, and the clickable text matches the source. An explicit text link must be unambiguous or include its column. Overlapping links are rejected.

There is a small cross-language detail here: Python string positions count Unicode code points, while JavaScript string slicing counts UTF-16 code units. The builder converts positions before rendering them in the browser:

start = len(line[:column].encode("utf-16-le")) // 2
end = start + len(link_text.encode("utf-16-le")) // 2

For example, in "😀send", Python places the s at index 1. JavaScript places it at index 2. Sending the Python index directly to JavaScript would put the link at the wrong position. The conversion concerns string indexing, not visual character width.

Even with correct offsets, the chosen definition can be conceptually wrong. Two objects can have the same name. A working preview proves that a source range exists; it does not prove that the author mapped the reference to the relevant object.

Keep evidence near the explanation

The reader can open selected definitions and inspect the diff beside the explanation. Notes point to the lines being discussed. The layout switch lets readers choose which pane comes first.

These are navigation choices, not evidence that the guide improves comprehension. The public Starlette example has five changed files, eight reading steps, and thirteen definition previews. Those counts describe its structure; they do not measure how well it teaches the change.

The output is one HTML file containing the source excerpts, explanations, styles, and scripts. Sharing it therefore shares the included source code too. The public example uses public Starlette code and includes its attribution.

Test the explanation with a reader

A next evaluation could ask a reviewer to explain a transition between two steps, identify the definition that justifies a claim, or point out a missing failure case. That would test something a line-range validator cannot.

No review-time benchmark or controlled comprehension study has been performed for this release. The upstream Starlette test suite was not run as part of generating the example, either. Building the guide should not be confused with testing the underlying change.

The unresolved question for me is how to find the missing connection in an otherwise complete-looking guide. Valid source references give the reader evidence to inspect. The explanation still has to earn their trust.

Implementation references

Builder at the version discussed here: snapshot resolution in build, source reconstruction in changed_files, and link checks in collect_links and append_link.
Public example manifest: the authored reading steps and definition mappings.

Writing disclosure: Codex drafted this article from my project, feedback I shared, and its source code. Codex checked the implementation descriptions against the pinned version linked above.