Process Optimization: Review/Scan → Comment → Fix Workflow

docs / process / process-optimization

← all docs

Process Optimization: Review/Scan → Comment → Fix Workflow

Applies the standard current-state / waste / future-state / impact framework to the process in process-operate-ocr.md.

1. Current State (as documented in the process doc)

Setup (once) → choose mode (review / scan / delegate) → run →
comments printed / posted to PR (human) → developer reviews comments →
fix + re-run, or adjust rule.json / dismiss → PR merges

Seven steps, three of them requiring a human in the loop (mode choice, comment triage, fix or dismiss), one of them spending model budget (the review/scan run itself; delegate spends the developer's own agent budget instead).

2. Identify Waste

Type Where it shows up Why it's waste
Waiting A CI-posted review comment sits on the PR until the author next opens it; no forcing function ties comment-triage to a review SLA The Run a Review or Scan → developer-triage handoff has no defined turnaround, same shape as VVAH's scan → triage gap.
Rework A budget-truncated run (--max-tokens-budget hit mid-way) reports partial, and if that isn't noticed the PR merges on an incomplete review Nothing forces a second look at partial/failed sessions before merge — see LLD §5 on how a session can legitimately end non-completed.
Handoffs Repo owner sets rule.json → CI runs ocr review → developer fixes or dismisses → (for delegate mode) developer separately configures their own coding agent's plugin Two to three handoffs depending on mode, each an implicit queue with no owner-defined SLA today.
Over-processing Re-running ocr scan on an entire repo repeatedly instead of scoping with --path, or not using --resume after an interrupted run --resume exists (content-fingerprint matched — LLD §8) but is opt-in per invocation, same habit gap as VVAH's --resume.
Manual work Provider/credential setup (Setup & Credentials) is a manual per-machine/per-CI-runner procedure; no shipped CI template ships with the pinned source clone Every team re-derives its own ocr review-in-CI wrapper from the README's Quick Start.
False-positive churn rule.json tuning happens reactively, one dismissed comment at a time, rather than as a scheduled review of dismissal patterns No cadence exists for someone to look at why comments get dismissed and adjust rules in bulk.

3. Future State (recommendations)

Recommendation Addresses Effort
Add a merge gate that treats a non-completed session as blocking, not just informational (fail CI on partial/failed unless explicitly overridden) Rework from unnoticed truncated reviews Low — CI wiring only, no OCR code change
Default every CI invocation to --resume (script it into the wrapper, same convention as Run a Review or Scan Step 2) Over-processing / repeated cost Low — wrapper-script convention
Define an SLA in the RACI: comment triage within 1 business day of a posted review; rule.json change requests reviewed within 2 business days Waiting, handoff drift Low — ownership/process, no tooling change
Ship a minimal CI job template (GitHub Actions) wrapping ocr review --resume + a PR-comment step, as a reusable artifact analogous to VVAH's proposed CI template Manual, duplicated CI wiring Medium — one-time authoring effort, reusable across teams
Monthly dismissal-pattern review: track which rules generate the most dismissed comments (from ocr session comments) and adjust rule.json in a batch, instead of ad hoc False-positive churn Low — reporting cadence, data already available per session
Batch credential setup across CI runners: script ocr config provider/ocr config model for repeat runner classes instead of the manual Setup & Credentials walkthrough each time Manual setup work Medium — one scripted install path per runner class

4. Estimated Impact

5. Implementation Plan

  1. Update process-operate-ocr.md's RACI/Metrics with the SLA additions above (process-only, do now).
  2. Add a --resume-by-default CI wrapper and job template under samples/ (next iteration).
  3. Add a monthly dismissal-pattern check to whoever owns rule.json for each repo.
  4. Revisit this document whenever process-operate-ocr.md's content changes materially.