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
- Who: Repo owner / tech lead, once per repository
- When: When onboarding a repo, or when credential policy changes
- How: Diff review (
ocr review) is the default for standard PR-based work. Full-fileocr scanis for auditing existing or unfamiliar code with no meaningful diff.ocr delegateis for teams that don't want OCR holding its own LLM API key — the review runs inside the developer's own coding agent instead. See HLD §3 for the full comparison. - Output: A documented mode choice per repo (e.g. in the repo's own README or CI config).
Step 2: Set up credentials (skip for delegate-only repos)
- Who: Whoever is onboarding the repo
- When: Once per machine or CI runner
- How: Follow Setup & Credentials — install
ocr, runocr config provider/ocr config model, verify withocr llm test. - Output: A working
ocr llm testround-trip.
Step 3: Author and maintain rule.json
- Who: Repo owner / tech lead
- When: At onboarding, then reactively as false positives surface
- How: Define include/exclude patterns and rule text per file type. Developers feed back dismissed comments; the owner batches those into rule adjustments (see Process Optimization for a recommended monthly cadence rather than one-off reactive edits).
- Output: A
rule.jsonthe team trusts enough not to routinely dismiss its output.
Step 4: Run OCR (local or CI)
- Who: Individual developer (local) or CI pipeline owner (automated)
- When: Per change, for
review; as needed, forscan - How: See Run a Review or Scan or Use Delegation Mode depending on the chosen mode.
- Output: Structured comments, printed to terminal or posted to the PR.
Step 5: Triage and act on comments
- Who: PR author, consulting the reviewer as needed
- When: Before merge
- How: Fix valid findings and re-run/re-push, or adjust
rule.json/dismiss false positives. Apartial/failedsession (budget-truncated or otherwise incomplete) should get a second look, not a silent merge — see Exceptions below. - Output: A PR ready to merge, with every comment resolved one way or another.
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 |