process-operate-ocr

docs / process / process-operate-ocr

← all docs

Process Document: Operate Open Code Review (OCR)

Owner: Repo owner / tech lead per repository | Last Updated: 2026-08-14 | Review Cadence: Quarterly

Purpose

Run OCR as a standing part of a team's development workflow — not just a one-off command — so that every diff gets a consistent, AI-assisted review with deterministic file selection and rule matching, and every review outcome (fix, dismiss, escalate) has a clear owner. Verified against the pinned source clone in samples/open-code-review/.

Scope

In scope: choosing a review mode per repository (review / scan / delegate), provider/credential setup, rule.json maintenance, running OCR in CI or locally, and triaging the comments it produces.

Out of scope: the model provider's own reliability/latency (that's the provider's problem, not OCR's — see Escalation); code review practices unrelated to OCR (pairing, design review); building OCR itself (see HLD / LLD instead).

RACI Matrix

Step Responsible Accountable Consulted Informed
Choosing review mode (review / scan / delegate) per repo Repo owner / tech lead Engineering manager Security (if repo handles sensitive data) Team
LLM provider & credential setup Whoever runs Setup & Credentials Repo owner Security (API key handling policy) Team
rule.json content (what gets reviewed, what rules apply) Repo owner / tech lead Engineering manager Developers (false-positive feedback) Team
Running ocr review in CI CI pipeline owner Repo owner — Developers (on PR comments)
Acting on a comment (fix / dismiss) PR author PR author Reviewer —
Delegation-mode plugin setup for a coding agent Individual developer Individual developer Platform docs —

Process Flow

Repo onboarded to OCR
        │
        ▼
  Choose mode ──► review (diff, the default) ──┐
        │                                       │
        ├──► scan (auditing unfamiliar code) ───┤
        │                                       ▼
        └──► delegate (no OCR-managed key) ──► Comments printed / posted to PR
                                                  │
                                                  ▼
                                     Developer reviews comments
                                          │              │
                                    valid finding   false positive
                                          │              │
                                          ▼              ▼
                                 Fix + re-run/push   Adjust rule.json or dismiss
                                          │              │
                                          └──────┬───────┘
                                                 ▼
                                            PR merges

Detailed Steps

Step 1: Choose a review mode

Step 2: Set up credentials (skip for delegate-only repos)

Step 3: Author and maintain rule.json

Step 4: Run OCR (local or CI)

Step 5: Triage and act on comments

Exceptions and Edge Cases

Scenario What to Do
A file must never be reviewed (generated code, vendored dependencies, secrets fixtures) Add an exclude pattern to rule.json (built on internal/config/allowlist's default-exclude patterns) rather than relying on developers to remember to skip it.
A review must not send code off-machine at all Use delegation mode — OCR never constructs an LLM client on that path.
A run is taking too long / costing too much Set --max-tokens-budget; OCR stops scheduling new files once the projected total would exceed it (bounded overrun — see LLD §6).
A run was interrupted (network blip, CI timeout) --resume <session-id>, never a full re-run — see Run a Review or Scan.
A session's terminal_state is partial or failed Treat as blocking, not informational — don't let it merge silently (see Process Optimization recommendation to make this an explicit CI gate).

Metrics

Metric Target How to Measure
Comment triage turnaround Within 1 business day of a posted review (proposed SLA — see Process Optimization) Time between CI comment post and PR author response
terminal_state distribution across CI runs completed for the large majority; partial/failed investigated, not ignored ocr session list / session manifests
Token usage per review Tracked, budget-gated via --max-tokens-budget Session manifest / retry report
False-positive rate (dismissed comments) Declining trend after each rule.json tuning pass Manual tracking from ocr session comments