DEV Community

YS Lee
YS Lee

Posted on

A PR walkthrough needs evidence between the steps

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."
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)