Reconciliation Display Improvements — Design Spec

Issue: #332 (P1-P7) Date: 2026-03-30

Problem

The reconciliation issue display is hard to interpret: the Expected/Actual details table has no document attribution (P1-P2), aggregations are opaque (P3), the useful summary gets equal weight to the noisy table (P4), field names are LLM free text (P5), document ordering is inconsistent (P6), and list views lack reconciliation status indicators (P7).

Solution

P1-P5: Summary-only reconciliation display

Drop the details field entirely. The summary becomes the sole vehicle for communicating reconciliation findings.

Prompt changes (reconciliation.clj system prompt):

• Remove details array from the output format
• Add guidance for rich summaries: name documents by type + reference number (not UUID), state the discrepancy with concrete values, attribute each value to its source document
• Example: "Invoice 2026-0199 charges EUR 250.00/unit for Externe SSD 1TB, but PO P-4412 specifies EUR 89.90/unit."

Schema changes (schema/matching.clj):

• Remove :details from ReconciliationIssue
• Existing DB data with details is harmless — Malli validates on write only

UI changes (shared.clj):

• Remove the [:details.issue-details ...] block from reconciliation-issues
• Each issue renders as: severity icon + summary text

P6: Document type ordering

Match cards: sorted by type priority (Contract → PO → Invoice → GRN), then by date within type.

Prompt: add instruction for the LLM to reference documents in procurement-flow order in summaries.

P7: Traffic-light match status badge on list views

New column: document.reconciliation_status (text, nullable). Values: null (no reconciliation), reconciled, incomplete, error.

Writer: reconciliation worker, after set-reconciliation!, iterates cluster documents, filters issues per document, computes status:

• No issues for this document → reconciled
• Only incomplete-coverage warnings → incomplete
• Any error-severity issue → error

Reader: list view query reads the column, renders badge color (green/yellow/red).

Files involved

• src/com/getorcha/workers/ap/matching/reconciliation.clj — prompt changes, per-document status writer
• src/com/getorcha/schema/matching.clj — remove :details from schema
• src/com/getorcha/app/http/documents/view/shared.clj — remove details table, match card ordering
• resources/migrations/ — new migration for reconciliation_status column
• List view query and template files — read and render the new column