From Diff to Decision: A Working Model of OCR

OpenCodeReview can now be viewed as one operating model rather than a collection of separate mechanisms. A requested Git change becomes evidence, policy narrows that evidence, grouping creates bounded context, and an agent works inside the resulting unit. This synthesis connects those stages so a reader can predict what OCR will do in a surprising case—and identify whether the cause belongs to Git input, deterministic scope, context formation, or model execution.

The useful judgment is not whether one stage is “smart.” It is whether responsibility is assigned to the stage that can enforce it. A ref should be resolved by Git-aware code, a project rule should be selected by ordered policy, a semantic relationship can be proposed by a model, and a model finding should remain inside the group and output boundary that can support it.

One review, several owners of state

The complete path begins before the LLM sees a line of code. The caller chooses workspace, commit, range, or scan semantics. In a historical review, OCR resolves the relevant commit or merge-base and reads the post-change file state from the selected ref. In workspace mode, it represents untracked files as additions and accepts that the working tree is a moving input. This first decision defines what “the change” means.

The Git provider then produces structured diffs rather than handing the agent an undifferentiated text stream. Paths, change status, hunks, and line counts become the raw material for the next boundary. Provider-level directory and ignore rules may remove paths before the per-file selection pass. The selection layer then applies its ordered gates: binary status, user exclusions, user inclusion, supported extension, default path rules, and the size or deletion outcome. The important state transition is from “changed in Git” to “selected for review.” Those sets are not identical.

For each selected file, rule resolution adds policy. The rule layer does not decide whether the file survived selection; it supplies the model with the concerns appropriate to that path. Custom, project, global, and embedded guidance are checked in order, with first match winning within a layer. A mixed group can retain path-specific rule blocks rather than collapsing them into one unlabelled instruction. The state is now more precise: the agent has not just a file, but a file plus the policy under which it should be interpreted.

Only then does OCR form the agent context. Related selected files may be grouped from metadata, subject to validity, size, and coverage safeguards. A failed grouping response returns to one-file units. A successful grouping response does not grant the group an unlimited repository view; it creates a shared conversation for the files assigned to that group. The plan phase, when warranted, organizes read-only investigation. The main phase adds comment production and completion tools. At every step, a model decision is surrounded by an engineering-owned transition.

flowchart LR A["Mode and ref"] --> B["Git evidence"] B --> C["Provider and file gates"] C --> D["Ordered rules"] D --> E["Metadata grouping"] E --> F["Plan and main review"] F --> G["Bounded findings"] G --> H["Coverage handoff"]

This chain explains why a review result can be useful even when it is not exhaustive.