SPEC-152-Q5b: Adviser Review View (Design Only)

Capability: SUITABILITY-ENGINE · Status: draft Repo: suitability-engine

This is a design specification and wireframe only. Per the 2026-08-16 scope decision: WTP does not build, host, or embed this UI anywhere — Origo’s own adviser-facing product implements it, if and how they choose, against the data this engine already produces. This document exists so that decision is made from a concrete design, not a vague intention.

1. Why this is a distinct surface from the client view

SPEC-004 describes the client’s view — polished, narrative, progressive-disclosure. An adviser needs the opposite: a dense, professional, audit-oriented view of the same derivation, used to review and sign off a report before the client ever sees it. Conflating the two (e.g. just giving an adviser the client view plus a “confirm” button) throws away exactly the information a professional reviewer needs — which rule produced which value, from which inputs, and where each of those inputs is sourced from.

2. Wireframe

Generated as a design reference (not implemented code) via Stitch. Shows the “Recommendation” section selected; the same table pattern applies to every section.

Key elements:

• Top bar — client identity, a review-status pill, a “Send to Client” action that is deliberately hard to trigger accidentally (locked/greyed until review is actually complete — mirrors the client view’s “disabled until required sections viewed” gate, but for the adviser’s own review completeness, not the client’s).
• Left rail — one entry per report section, each with a status dot (not-reviewed / needs-attention / clear) so an adviser scanning many reports in a queue can see at a glance which need work.
• Main panel — a dense field-level table, not narrative cards: Field / Value / Source Class / Auto-sourceable / Rule ID / Source Inputs / Actions. This is the derivation audit trail made legible to a human reviewer. (The wireframe image predates the #14 decision and still shows a single graded “Confidence” column — read that column as the two categorical columns above; see §3. Regenerating the image is tracked in #64.)
• Audit trail footer — a raw, timestamped system log (engine version, template version, override events) for the rare case a reviewer needs the literal record, not just the summarised table above it.

3. Data mapping — and what “confidence” actually means here

The table’s core columns map to DerivationAuditEntry (src/suitability-rules/types.ts), returned as part of the audit object in POST .../suitability/export?format=json’s response ({ data, audit }) — already returned today, and currently unused by the client view spec, since a client should never see raw rule IDs or source-field names:

Wireframe column	Source
Field	DerivationAuditEntry.fieldPath
Value	DerivationAuditEntry.output
Rule ID	DerivationAuditEntry.ruleId
Source Inputs	DerivationAuditEntry.inputs (keys)
Source Class	FieldTraceEntry.sourceClass (src/suitability-readiness/trace.ts)
Auto-sourceable	FieldTraceEntry.autoSourceable

There is no graded “Confidence” column — by decision, not omission. Grounding the original wireframe in the real API showed that the High/Medium/Low “Confidence” badge it drew does not correspond to anything the engine computes. SPEC-152’s prose (“RAG confidence travels with every field”) overstated what exists (amendment tracked in client-onboarding#2808). What is actually implemented (suitability-readiness/trace.ts’s FieldTrace) is, per template variable:

• a categorical sourceClass — Enable | Holdings | Spreadsheet | Calc | Config | Manual | New | Unknown — naming where that variable’s value comes from; and
• an autoSourceable boolean — whether the engine can populate it without manual input.

Decision (#14, Rob, 2026-09-30 — Option A): drop the numeric/graded confidence concept. An adviser view shows sourceClass and autoSourceable directly, as what they are — no mapping onto a 3-tier badge (e.g. autoSourceable: true → “High”) that would imply more precision than the data carries. No engine change is needed; both fields are already produced.

Two caveats anyone building this for real still needs:

1. FieldTrace is template-level, not client-level. It describes which variables a template uses and where each is sourced from — it is the same for every client rendered against that template. It says nothing about the quality of a specific client’s derived value.
2. FieldTrace and DerivationAuditRecord are not currently joined anywhere in this codebase. FieldTrace operates on a parsed template; DerivationAuditRecord operates on a specific client’s derived values. Putting both on one table row means joining them by field path/variable name in the consuming UI (or a future engine helper) — straightforward, but not a lookup that exists today.

Graded per-value scoring (joining the two and grading each client’s value) is not planned; revisit only if an adviser reviewer workflow shows the categorical signal is genuinely insufficient.

4. What this spec deliberately does not include

• No working reference implementation (unlike SPEC-004) — the 2026-08-16 scope decision was design spec + wireframe only for this surface, since WTP will never operate it.
• No auth/session model — Origo’s adviser authentication is entirely their own concern; this engine has no adviser-identity concept at all.
• No “Override” persistence design — the wireframe shows an Override action per row (an adviser correcting a derived value before send) but this spec does not design where that override is stored, how it re-enters the pipeline, or how it’s audited. A real implementation needs that design; it’s flagged as follow-up scope, not solved here.
• No multi-report queue/worklist UI — the wireframe shows one report’s review state; a real adviser tool almost certainly needs a list view across many clients, entirely out of scope here.

5. Traceability

• Companion: SPEC-004 (client view)
• Data source: src/suitability-rules/types.ts (DerivationAuditEntry), src/suitability-readiness/trace.ts (FieldTrace)
• Feeds: any future Origo-side adviser tooling decision — not a WTP build item