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 how confident the system is in each one.

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 / Confidence / Rule ID / Source Inputs / Actions. This is the derivation audit trail made legible to a human reviewer.
• 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 a real gap this surfaces

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)

The “Confidence” column does not map cleanly to anything that exists today — found while grounding this wireframe in the real API, not assumed going in. SPEC-152’s own prose describes “RAG confidence travels with every field,” but what’s actually implemented (suitability-readiness/trace.ts) is a categorical sourceClass (Enable | Holdings | Spreadsheet | Calc | Config | Manual | New | Unknown) plus an autoSourceable boolean — a template-level trace of which variables a template uses and where they come from, not a per-derived-value graded confidence rating joined to a specific client’s audit entries. Two consequences for anyone building this for real:

1. A believable interim mapping exists (autoSourceable: true → High, false → Low, no “Medium” tier yet) but it’s a simplification the wireframe doesn’t disclose visually — a real implementation should either build genuine graded confidence scoring or present the categorical sourceClass directly rather than dressing it up as a 3-tier badge that implies more precision than exists.
2. FieldTrace and DerivationAuditRecord are not currently joined anywhere in this codebase. FieldTrace operates on a parsed template (which variables it uses); DerivationAuditRecord operates on a specific client’s derived values. Building the table above for real means joining them by field path/variable name — genuine integration work, not a data lookup that already exists.

This is disclosed here rather than left implicit in the wireframe, so Origo doesn’t build against a confidence signal that turns out to be thinner than it looks.

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