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
- Cycle time (review → merge): formalizing the triage SLA and defaulting to
--resumeremoves the dominant source of delay (waiting between handoffs) without any OCR change — a process-discipline win, mirroring VVAH's equivalent finding. - Wasted spend: a merge gate on non-
completedsessions and habitual--resumeremove the two most expensive rework paths (merging on an incomplete review, re-paying the full review cost after an interruption) at effectively zero implementation cost. - Signal quality: a scheduled dismissal-pattern review turns
rule.jsontuning from reactive one-offs into a deliberate, batched process — reducing the false-positive rate developers experience over time.
5. Implementation Plan
- Update
process-operate-ocr.md's RACI/Metrics with the SLA additions above (process-only, do now). - Add a
--resume-by-default CI wrapper and job template undersamples/(next iteration). - Add a monthly dismissal-pattern check to whoever owns
rule.jsonfor each repo. - Revisit this document whenever
process-operate-ocr.md's content changes materially.