POA Operator Repair
Summary
POA repair is the human-in-the-loop part of the module. It turns ambiguity into explicit operator tasks, field controls, diagnostics, corrections, and retry paths. The repair surface is where POA proves that automation is not the final authority.
The existing concept page POA Operator Repair Surface is the deeper implementation orientation. This thread explains how repair fits inside the full workflow.
Reader Question
When POA cannot safely advance automatically, how does an operator correct the state and resume processing without losing evidence or auditability?
Surface Or Workflow
Operators repair from case detail, document repair workspace, document-kind forms, issue callouts, command diagnostics, and retry controls. Engineers enter through repair field builders, issue projections, read models, locks, repair actions, diagnostics routes, and tests for invoice, confirmation, and packing slip repair.
Lifecycle
The lifecycle starts when interpretation, matching, validation, or command execution produces an issue. The console projects that issue into a repairable view, showing the current evidence and only the controls relevant to the document kind. The operator saves corrections or retries without edits when the underlying state has changed.
The service layer persists manual corrections, records actor context, rebuilds review snapshots or target projections, and decides whether the case can continue. Retry re-enters the same processing path rather than creating a special UI-only completion mode.
Child Threads
- POA Matching And Validation Workflow: produces many of the repairable issues.
- POA External Sync Workflow: covers command failures and manual handling.
- Review Primitives: provides the shared vocabulary for issues, review tasks, locks, and audit timelines.
Implementation Boundaries
Repair UI lives in app/web/app/poa-greenfield/components. Operator read models, repair field descriptors, review scope, issue projection, and command diagnostics live under services/poa/api/greenfield/operator. Durable repair behavior lives under services/poa/review/workflow, and diagnostic projections live under services/poa/diagnostics.
Tradeoffs
Typed repair controls are more work than a generic JSON editor, but they make operator changes auditable and domain-aware. That gives the workflow enough structure to resume safely while still allowing human correction.
Visual
The current visual is a graph neighborhood. The intended visual is a repair loop from issue projection to field affordance, operator correction, projection rebuild, retry, and resumed processing.
Source Evidence
docs/engineering/concepts/poa-operator-repair-surface.mdapp/web/app/poa-greenfield/components/RepairPanel.tsxapp/web/app/poa-greenfield/components/DocumentRepairWorkspace.tsxservices/poa/review/workflowservices/poa/api/greenfield/operatorservices/poa/diagnosticstests/poa/test_poa_review_repair_workflows.pytests/poa/test_poa_operator_repair_workflows.py