File review workflow

The file review workflow is two surfaces: the review queue at /demo/principal/reviews and the per-case review workspace at /demo/principal/reviews/[id]. The rubric swaps by skin and by the AR’s appointment type:

• Full ARs in a mortgage network: MCOB (Heritage).
• Full ARs in a GI network: ICOBS (Crown).
• Full ARs in a credit-broking network: CONC (Pinpoint).
• IARs in any network: a narrowed IAR rubric (introduction quality, status disclosure, scope adherence, hand-off).

Score every case against the rule that actually applies. See File-review rubrics for every item and Case-file contents for what the reviewer is reading when they score it.

Live: lending-agent-oversight.vercel.app/demo/principal/reviews.

Sampling cadence

The product expects file reviews to run on a sampling cadence rather than ad-hoc. Default cadences in the demo:

• High and Critical risk band: monthly review, 5% sample of new cases.
• Elevated risk band: quarterly, 3% sample.
• Moderate risk band: half-yearly, 1% sample.
• Low risk band: annual, 1% sample.

Sampling is deterministic and seeded against the AR’s id. The queue surfaces sampled cases, and the principal-compliance officer works through them.

The review queue

Renders at /demo/principal/reviews.

• Header: File reviews, count chip, Open | Closed | All segmented control.
• Filter bar: AR, sample reason (sampling rule applied), date range, reviewer.
• Each row card shows: AR trading name (linked), case reference, sampled-on date, days-open counter, current aggregate score (if scoring started), reviewer assigned (or Unassigned).

Click a row to enter the review workspace.

The review workspace

Renders at /demo/principal/reviews/[id]. Two-pane layout.

Left pane: case facts

• AR header (compact): trading name, FRN, type chip, link out to AR detail.
• Customer reference (anonymised, e.g. Customer ref CUS-44218).
• Case summary in muted text: product, sale date, sale value, adviser.
• Case timeline: when the case was opened, key events, when the file was sampled.
• Source documents list: each is a card with a name and a (placeholder) View button. In production these resolve to a signed file URL.

Right pane: rubric checklist

The per-skin rubric. One section per topic, one row per item.

Skin	Rubric	Sample sections
Heritage Mortgage Network	MCOB	Suitability (MCOB 4.7A), Affordability (MCOB 11.6), Disclosure (MCOB 5), Fees (MCOB 4.4A)
Crown GI Collective	ICOBS	Demands and needs (ICOBS 5.2), Suitability (ICOBS 5.3), Disclosure (ICOBS 6), Claims (ICOBS 8)
Pinpoint Credit Network	CONC	Pre-contract (CONC 4.2), Creditworthiness (CONC 5.2A), Communications (CONC 3), Forbearance (CONC 7)

Each item is rendered with:

• Handbook reference (e.g. MCOB 11.6.5) in monospace.
• Item label (e.g. “Stress test applied for interest rate increases”).
• Scoring control: a four-button segmented control: Pass, Advisory, Fail, N/A. Colour-coded against the family’s severity palette.
• Findings textarea, expandable on focus. Free-text, supports multi-line.

Below the rubric

• Root-cause taxonomy. Multi-select chips: training-gap, system-failure, process-omission, intentional-misconduct, third-party-error, documentation-quality, supervision-failure, control-bypass.
• Aggregate score. Auto-derived from item scores. Pass = 1.0, Advisory = 0.7, Fail = 0.0, N/A excluded from the denominator. Percentage shown as a banded badge (>= 90% green, 70-89% amber, < 70% destructive).
• Reviewer notes. Optional free text.
• Close review primary button. Disabled until every non-N/A item is scored.

Closing a review writes the FileReview record into the store, recomputes the AR’s risk score (the file-review-inverse input), and surfaces the review on the AR’s detail page on the File reviews tab.

States

• Loading. Server-rendered with the rubric and case facts.
• Empty queue. “No cases sampled for review this month.”
• Empty rubric. Not possible: the rubric is loaded from lib/rubrics.ts per skin and is non-empty.
• In progress. A “Save draft” outline button (top-right) writes the partial state to localStorage. Coming back to the review picks up where it left off.
• Action-pending (closing review). Primary button shows a spinner for 400ms, then a confirmation toast, then routes back to the queue with the closed review removed from Open and visible under Closed.
• Validation failure. If the visitor tries to close with unscored non-N/A items, the relevant rows highlight with a 2px destructive ring and the close button shows “Score X items first” in muted text below.
• Error. Error boundary on the rubric pane; case facts pane renders independently.

Responsive behaviour

• Mobile (< 640px). Single column. Case facts collapse to a top accordion. Rubric below. Reviewer panel pinned to the bottom of the page (sticky on scroll).
• Tablet (640-1024px). Two-column at narrow widths.
• Desktop (> 1024px). Full split. Max-width 1440px to accommodate the rubric width.

Components

• components/principal/file-review-workspace.tsx (top-level)
• components/principal/file-review-checklist.tsx (per-skin rubric)
• lib/rubrics.ts (rubric definitions, items keyed by handbook reference)

How this connects to the rest of the demo

• The queue picks up sampling decisions per AR; closing reviews here is what populates the File reviews tab on AR detail.
• The aggregate score feeds the file-review-inverse input on the AR’s risk score (default weight 0.25).
• The KPI tile “Overdue file reviews” on the principal home deep-links here pre-filtered.
• The review’s findings and root-cause taxonomy roll up into the annual fitness review packet under the File reviews section.
• For the per-skin rubric in full, see Architecture · Rubrics.