What makes a review picture useful

PR Lens is most useful when its parts are read as one chain of evidence rather than as separate features. This checkpoint connects the graph model to the diff that feeds it, the validation and corrections that constrain it, and the reading path that it offers to a reviewer. The practical judgment is simple: before trusting a picture, ask where its facts came from, what context it kept, what repository intent changed it, and which question each view helps you answer.

A graph has a chain of authority

The graph begins with a comparison between two repository states. That starting point is not a technical preamble; it sets the boundary of the story. PR Lens uses the merge base and the proposed head so the change describes work introduced on the pull-request branch. Git supplies the commit identities, changed-file information, and line counts. The patch supplies the material from which responsibilities and relationships can be inferred.

The model contributes a different kind of information. It proposes which responsibilities deserve nodes, which boundaries deserve lanes, and which calls or events deserve edges and flow messages. It can turn a scattered set of edits into a sentence about system behavior. In the broadcast example, it can recognize that a queue route now leads to a bulk sender, that suppression filtering occurs before the send, and that the old per-recipient path has been retired. Those relationships are valuable precisely because they are not written as one ready-made sentence in the diff.

But a model proposal does not become a repository fact merely because it is fluent. The CLI replaces the model’s versions of provenance, requested lenses, generation time, and diff statistics with values it already knows. This creates a useful chain of authority. Git says which transition was compared. The model proposes a human-readable account of the transition. The graph contract checks whether that account is internally coherent. A repository correction can then express a durable presentation choice, such as a stable name or boundary, without pretending that the model discovered it anew.

The chain is easier to inspect when each link has a different job. If an edge has the wrong endpoint, the document has a structural problem. If the edge connects real nodes but the model missed a relevant dependency, the document has a semantic problem. If the node is valid but its label conflicts with a repository’s established language, the issue is a correction problem. Treating all three as “AI quality” hides the remedy. The first needs a contract repair, the second needs better analysis or human authorship, and the third needs durable repository intent.

flowchart LR D[Merge-base diff] --> M[Model proposal] M --> F[Known repository facts] F --> V[Contract and integrity checks] V --> C[Durable corrections] C --> G[Scoped graph for review] V --> X[Named failure]

This is also why validation belongs between inference and rendering. A graph with a broken edge cannot communicate a blast radius, no matter how attractive its cards look.