Treatment Pipeline Manager – UX Specification

Related Technical Authority: Treatment Pipeline Manager – Technical Specification

1. Purpose

This UX specification governs the staff-facing experience for Primoro's treatment pipeline — the operational engine that turns patient enquiries into booked appointments. It defines how clinical and front-of-house staff discover, triage, qualify, and progress Leads and Opportunities through a governed conversion journey. The primary roles it serves are Treatment Coordinator, Front Desk, Practice Manager, and Admin.

2. Core UX Principles (Non-Negotiable)

These principles take precedence over visual preferences. If a design choice conflicts with a principle below, the principle wins.

• Action-first — users see the action they need next, not abstract status displays.
• Governance always visible — when AI is involved, users always know what AI did and what they're confirming.
• No dead toggles — every UI control either does something or doesn't appear.
• Calm by default — the interface gets out of the way; alerts are reserved for things that genuinely need attention.
• Progressive disclosure — advanced detail is one click away, not always-on.
• Eligibility as a gate, not a hint — BookingEligibility status must be prominent and unambiguous; no surface may allow a booking action when eligibility is false. Inferred from the technical spec's §5 and §14.2 rule 2, which make eligibility the single authoritative gate across all channels.
• AI contribution always attributed — wherever AI-supplied data (triage summaries from AI Concierge or Aiden) appears in a Lead or Opportunity record, it must be visually distinguished from staff-entered data. Inferred from technical spec §7 AI boundaries and §8.1 AI involvement markers.
• Irreversibility is announced — stage transitions that cannot be undone (e.g. advancing past Booking Permitted, marking Lost / Closed) must require explicit confirmation and must show what cannot be reversed. Inferred from technical spec §3.3 rule: records that have reached Booking Permitted, Booked, Converted, or Lost / Closed must not be returned to earlier stages.

3. Design Philosophy

The mental model is a governed sales funnel with clinical guardrails. Every record on screen has exactly one current stage, one owner, and one clear next action — the interface must make all three visible at a glance without requiring the user to open a detail view. Inferred from the technical spec's §3.3 state machine, §4 Stack and SLA model, and §14.4 saved-view requirements.

Empty states signal readiness, not absence. An empty "My Pipeline" view means the current user has no assigned records, which is a valid and positive state; the empty state should confirm this clearly rather than imply an error. Inferred from the §14.4 saved-view definitions.

Error states distinguish user-correctable errors (e.g. attempting to advance a stage without completing required triage artefacts) from system errors (e.g. a failed stage-transition write). User-correctable errors must identify what is missing; system errors must invite retry or escalation. Inferred from §14.2 rules 1–3 and §14.2 rule 6.

AI suggestions are advisory and visually subordinate. AI-supplied triage summaries and stage-transition recommendations are presented as suggestions awaiting staff confirmation, with clear attribution to the AI channel that generated them. No AI suggestion executes automatically. Inferred from technical spec §7 AI boundaries.

Multi-step flows (such as setting BookingEligibility = true) are presented as short, confirmable wizards rather than single-click actions, both to communicate the significance of the action and to satisfy the MFA policy where enabled. Inferred from §9 access control table and the MFA requirement in that section.

Read-only vs editable surfaces are unambiguous. Fields that are system-derived or AI-supplied (e.g. EstimatedValue, TriageSummary) are visually distinct from staff-editable fields. Inferred from technical spec §3.2 (EstimatedValue is read-only) and §7 AI boundaries.

Undo/redo is not available for stage transitions, because all transitions are committed with an immutable audit entry. The design must communicate this clearly before the user commits. Inferred from §8.1 and §14.2 rule 6.

4. Primary Surfaces

4.1 Web Portal

Who uses it: Treatment Coordinators, Practice Managers, Front Desk staff, and Admins. This is the primary operational surface for the module. Inferred from technical spec §6.1 and the role table in §9.

Key tasks performed here:

• Browse all Leads and Opportunities grouped by Stack and stage, with filtering by SLA status, owner, and BookingEligibility. Inferred from §6.1 and §14.4.
• Open and review a Lead or Opportunity detail view, including the full conversation thread reference and AI-supplied triage summary. Inferred from §3.1 and §3.2 minimum required fields.
• Update triage artefacts on a Lead or Opportunity. Inferred from §9 role table: Treatment Coordinator and Practice Manager may update triage artefacts.
• Advance a pipeline stage (for authorised roles), with confirmation for irreversible transitions. Inferred from §3.3 and §9.
• Set BookingEligibility = true via a governed, confirmable action (with MFA step where practice policy requires it). Inferred from §5, §9, and the MFA note in §9.
• Accept or reject an AI-recommended stage transition. Inferred from §7: AI MAY recommend stage transitions but MUST NOT execute them; a staff actor must confirm.
• Mark a record as Lost / Closed, with a mandatory lost reason. Inferred from §8.2 OpportunityLost event payload, which requires LostReason.
• Defer an Opportunity with a future review date. Inferred from §8.2 OpportunityDeferred event payload, which requires ReviewDateUTC.
• Configure Stacks and Stage Templates (Practice Manager and Admin only), via the Admin Control Plane surface embedded in or linked from the portal. Inferred from §14.3 configuration table.
• Export the audit log (Admin only). Inferred from §9 role table.
• Use saved views: "Booking Ready", "Emergency", "My Pipeline". Inferred from §14.4.

Layout pattern: list-detail at the pipeline level (left-hand stack/stage grouping with a right-hand record detail pane), switching to a form / wizard pattern for multi-step governed actions such as setting eligibility or closing a record. Inferred from §6.1 pipeline view description and the multi-step nature of eligibility-setting implied by §5 and §9.

4.2 Tablet App

Who uses it: Front Desk staff and Treatment Coordinators working at the practice reception or in the practice environment. Inferred from technical spec §6.2.

Key tasks performed here:

• Review incoming Leads awaiting triage, with enough context (source channel, urgency signal, AI triage summary) to act quickly. Inferred from §6.2 triage and booking readiness dashboard description, and from the intake endpoint response fields in §10.3.
• Confirm triage completeness for a Lead before handing off to Appointment Manager. Inferred from §6.2: "confirm triage completeness and hand off to Appointment Manager when eligibility is confirmed".
• View whether BookingEligibility is true for a given record (read-only on tablet for Front Desk; editable only for authorised roles). Inferred from §9 role table and §6.2.
• View the current Pipeline Stage and next-action requirement for each record. Inferred from §10.3 response field NextActionRequired and §4 SLA model.

Touch ergonomics: glove-friendly tap targets ≥48 px. Emergency Stack records must be visually distinct and surfaced at the top of any triage list to support the 72-hour SLA. Inferred from §4.3 Emergency Stack Contract and the clinical practice context implied throughout the technical spec.

4.3 Mobile App (Patient or Staff)

Treatment Pipeline Manager has no direct patient-facing surface. The technical spec §6.3 states this explicitly: "Treatment Pipeline Manager has no direct patient-facing surface. Patients interact via Aiden (website) or AI Concierge (voice)." No staff-specific mobile surface is described in the technical spec; if a future mobile staff surface is added, this section should be revisited.

(needs UX writer input — confirm whether any lightweight staff-mobile notification or read-only summary view is in scope for Post-MVP, or whether this surface is formally out of scope)

5. Interaction Model

5.1 Primary Flows

Flow 1 — New Lead arrives via AI channel (AI Concierge voice or Aiden website)

Inferred from technical spec §10.3 intake endpoint contract, §3.1 Lead creation rules, and §6 delivery surfaces.

AI Concierge / Aiden calls intake endpoint
        │
        ▼
Treatment Pipeline Manager creates Lead
  (BookingEligibility = false, Stack assigned,
   Stage = New Enquiry, ConversationThreadID stored)
        │
        ▼
Task Manager trigger emitted → staff notified of new Lead
        │
        ▼
Front Desk / Treatment Coordinator opens Lead in web portal or tablet
        │
        ▼
Staff reviews AI triage summary (attributed, read-only)
        │
        ├─ Triage artefacts incomplete?
        │       │
        │       ▼
        │   Staff completes missing triage fields
        │
        ├─ AI recommends stage advance?
        │       │
        │       ▼
        │   Staff reviews recommendation → accepts or rejects
        │
        ▼
Treatment Coordinator / Practice Manager sets BookingEligibility = true
  (confirmation step; MFA if practice policy requires)
        │
        ▼
Stage advances to Booking Permitted
  (AuditTrail updated; BookingEligibility change event emitted to Appointment Manager)
        │
        ▼
Appointment Manager handles slot selection [out of scope for this module]

Flow 2 — Lead converted to Opportunity

Inferred from §3.2, §3.3, and §10.4 unified conversation thread contract.

Authorised staff converts qualified Lead
        │
        ▼
Treatment Pipeline Manager creates Opportunity
  (PatientID linked, ConversationThreadID carried forward,
   Stage = Qualified or Booking Permitted as appropriate)
        │
        ▼
Segmentation event emitted if applicable (e.g. LeadNurtureEligible superseded)
        │
        ▼
Opportunity appears in pipeline view; previous Lead is closed / converted

Flow 3 — ProposalAccepted event drives Opportunity advance

Inferred from §3.3.1, and from Smart Treatment Proposals technical spec §3.2 (six proposal states) and STP UX §2 (state integrity made tangible).

Before a ProposalAccepted event can legitimately drive a pipeline advance, the linked Smart Treatment Proposal must be in the Accepted state (not merely Presented, Explained & Acknowledged, or any other intermediate state). The pipeline UI must surface the current proposal state — Draft, Presented, Explained & Acknowledged, Accepted, Declined, or Expired — on the linked Opportunity's detail view, so staff can verify correct state prior to any stage advance. A pipeline move MUST NOT be triggered if the proposal is in any state other than Accepted; if the Opportunity detail view shows a proposal in an earlier state (e.g. Presented or Explained & Acknowledged), the stage-advance action for that trigger path must remain unavailable, and the UI must indicate that acceptance is still required. Inferred from STP technical spec §3.2 and STP UX §2 "State integrity made tangible" principle.

Smart Treatment Proposals emits ProposalAccepted event
  (carrying LinkedOpportunityID, ProposalID)
  [Proposal state = Accepted — pipeline advance permitted]
        │
        ▼
Opportunity detail view displays proposal state badge: "Accepted"
  (AI attribution badge applied if proposal was AI-assisted)
        │
        ▼
Treatment Pipeline Manager evaluates outstanding triage artefacts
        │
        ├─ Triage incomplete → BookingEligibility remains false
        │       Staff notified via Task Manager trigger
        │       Proposal state badge remains visible; no pipeline advance
        │
        └─ Triage complete → BookingEligibility = true
               Stage advances to Booking Permitted (or Converted if already eligible)
               AuditTrail records Trigger = ProposalAccepted + ProposalID
               BookingEligibility change event emitted to Appointment Manager

If the linked proposal transitions to Declined or Expired before a pipeline advance has occurred, the Opportunity detail view must reflect this change in the proposal state badge, and any pending AI-recommended stage advance based on that proposal must be withdrawn or flagged as no longer valid. Inferred from STP technical spec §3.2 downstream implications and the governance-always-visible principle.

Flow 4 — Record closed as Lost / Closed

Inferred from §3.3, §8.2 OpportunityLost event, and §9 role table.

Authorised staff (Treatment Coordinator, Practice Manager, Admin)
initiates close action on Lead or Opportunity
        │
        ▼
Confirmation modal: irreversible transition warning displayed
  Staff enters or selects LostReason (mandatory)
        │
        ▼
Stage set to Lost / Closed
  AuditTrail updated
  OpportunityLost segmentation event emitted to Campaign Manager (if Opportunity)
  Communication Hub notified via stage-change event

Flow 5 — Emergency Stack record lifetime management

Inferred from §4.3 and §14.2 rule 7.

Emergency Stack Lead created (72-hour clock starts)
        │
        ▼
Record surfaced at top of triage list with visual urgency indicator
SLA countdown visible on record
        │
        ├─ Approaching 72-hour threshold →
        │     Task Manager trigger emitted (staff follow-up required)
        │     In-app alert surfaced to record owner
        │
        └─ Not resolved within 72 hours →
              Record flagged for escalation or closure
              Escalation alert visible to Practice Manager

5.2 State Machines (Mirror of Technical Spec § 3.3)

The following table maps each pipeline state to its UX treatment. Inferred from technical spec §3.3 and §14.2 rules.

Irreversible transitions (to Booking Permitted, Booked, Converted, Lost / Closed) must display a confirmation step that explicitly states the transition cannot be undone. Inferred from §3.3 rule: records reaching these states must not be returned to New Enquiry or Awaiting Triage, and from §14.2 rule 6 requiring audit commit before transition.

AI-recommended stage transitions must be presented as a distinct suggestion card or inline suggestion, visually differentiated from a staff-initiated action (e.g. using an AI attribution badge). The staff member explicitly accepts or dismisses the suggestion before any transition fires. Inferred from §7: AI MAY recommend transitions but MUST NOT execute them.

5.3 Empty / Loading / Error / Offline States

The following definitions apply to all pipeline list and detail views. Inferred from §6.1, §14.4 saved views, and general platform patterns.

Pipeline list view (all records)

• Empty state: If no records match the current filter or saved view, display a contextual message indicating no records match — not a generic "no data" screen. For "My Pipeline", confirm that the user has no assigned records. Inferred from §14.4 saved-view semantics. (needs UX writer input — exact empty-state copy per saved view)
• Loading state: Skeleton rows matching the list layout; no spinner-only states that block interaction. Inferred from the clinical-workflow context where staff need immediate feedback.
• Error state: If the pipeline list fails to load, display a retriable error with an option to reload. Do not display a partial or stale list without labelling it as potentially out of date. Inferred from §15 reliability requirements.
• Offline state: The pipeline list requires live data (BookingEligibility must not be cached per §5). Display a clear offline indicator; disable all write actions; allow read of any locally cached record data with a "data may be outdated" label. Inferred from §5 and §15 availability requirements.

Lead / Opportunity detail view

• Empty state: N/A — detail view is only reachable from an existing record.
• Loading state: Skeleton layout matching the detail pane structure; AI-supplied fields (triage summary) may load asynchronously and should show a subtle loading indicator in their field area rather than blocking the whole pane.
• Error state: If a stage transition fails to commit (e.g. write error), the UI must roll back the visual state to the pre-transition state and display an actionable error. It must not leave the UI in a state that implies the transition succeeded when it did not. Inferred from §14.2 rule 6: audit must be recorded before transition commits.
• Offline state: All write actions (stage advance, eligibility change, triage update) are disabled when offline. The record is displayed read-only with an offline indicator.

BookingEligibility confirmation step

• Error state: If MFA fails or times out, the confirmation step must remain open (not dismiss) and surface a clear error with a retry option. The eligibility value must not change unless the full confirmation succeeds. Inferred from §9 MFA requirement and §14.2 rule 3.

5.4 AI Concierge Out-of-Hours and Overflow Lead Intake

Inferred from AI Concierge module specification (out-of-hours and overflow recovery handling) and technical spec §10.3 AI Concierge Intake Endpoint Contract.

AI Concierge handles inbound voice calls during out-of-hours periods and overflow conditions (i.e. when front-of-house staff are unavailable), creating intent-aware context that is deposited into the pipeline via the intake endpoint. Leads arriving through this channel carry a SourceChannel value indicating AI Concierge origin, and may carry a richer initial triage payload than Leads originating from other channels — including call intent signals, urgency flags, and a structured voice-call triage summary.

The pipeline UI must surface this context clearly so that staff reviewing the Lead during the next available working period can act on it without needing to replay or re-read the original call transcript. Specifically:

• Source channel indicator — the Lead card and detail view must display the SourceChannel as "AI Concierge (Voice)" in the record header, visually distinct from web-origin Leads (e.g. Aiden). This allows staff to immediately identify that the Lead originated from an unattended call and adjust their review accordingly. Inferred from §3.1 SourceChannel enum and §10.3 intake endpoint contract.
• Out-of-hours context badge — where the intake timestamp indicates the Lead was created outside of configured practice hours, an "Out-of-hours intake" label SHOULD be shown on the Lead card and detail view. This signals to the reviewing staff member that the patient may have had no live interaction and could be expecting a follow-up call. (needs UX writer input — confirm whether practice-hours configuration is surfaced to the pipeline module or must be inferred from intake timestamp alone)
• AI voice triage summary — any triage summary or intent signal supplied by AI Concierge at intake is displayed using the standard AI attribution badge (naming "AI Concierge" as the originating channel), read-only, and visually distinct from any subsequent staff-entered triage notes. Staff must not be able to overwrite the AI-supplied summary; they may add their own triage notes alongside it. Inferred from §7 AI boundaries, §8.1 AI involvement markers, and §10.3 intake endpoint response fields.
• Urgency signal propagation — if AI Concierge flagged the call as urgent at intake (e.g. pain-related or time-sensitive presenting concern), this urgency signal must be reflected in the Stack assignment and, where applicable, must trigger Emergency Stack handling with the 72-hour SLA indicator. The urgency flag must not be silently dropped or require staff to re-derive it from the triage summary. Inferred from §4.3 Emergency Stack Contract and §10.3 intake endpoint contract.
• Next-action surfacing — Leads created by AI Concierge during out-of-hours or overflow periods will commonly arrive with BookingEligibility = false and a NextActionRequired value indicating staff review is needed. The pipeline list view must surface these Leads prominently in the "My Pipeline" and triage views at the start of the next working session, so staff do not need to manually search for overnight or overflow intakes. Inferred from §6.2, §10.3 NextActionRequired response field, and §14.4 saved-view definitions.

The interaction pattern for acting on an AI Concierge-sourced Lead (reviewing triage summary, completing missing artefacts, setting eligibility) follows Flow 1 (§5.1) in all other respects. The source-channel distinction is presentational and contextual; it does not alter the governed stage-transition rules.

6. Component Inventory

New components introduced or extended by this module:

• Pipeline stage badge — displays the current pipeline stage with semantic colour treatment; used on Lead and Opportunity cards and detail headers. Inferred from §3.3 state machine and §14.4 filtering requirements.
• BookingEligibility gate indicator — a prominent, unambiguous display of whether booking is permitted on a given record; appears on both the list card and the detail view. Must not be actionable for roles that cannot set eligibility. Inferred from §5 and §9.
• AI attribution badge / field marker — a visual indicator applied to fields or suggestions that were supplied by an AI channel (AI Concierge triage summary, Aiden triage data, AI stage-transition recommendation). Includes the name of the AI channel that supplied the data. Inferred from §7 and §8.1 AI involvement marker requirements.
• Stage transition confirmation modal — a confirmable, blocking modal used for irreversible stage transitions; includes the destination state, a warning that the action cannot be undone, and (for Lost / Closed) a mandatory LostReason field. Inferred from §3.3 irreversibility rules and §8.2 LostReason requirement.
• BookingEligibility confirmation wizard — a short multi-step flow (minimum: summary of what is being confirmed, MFA step if required, final confirm) for setting BookingEligibility = true. Distinct from a simple modal because MFA may interject. Inferred from §5, §9, and §14.2 rule 3.
• SLA countdown indicator — a visual indicator of SLA status (on track / at risk / breached) on list cards and detail views; for Emergency Stack records, displays a 72-hour countdown. Inferred from §4.3 and §14.4 filter by SLA status.
• AI suggestion card — an inline card presenting an AI-recommended stage transition, with accept and dismiss actions, AI channel attribution, and the triage rationale that triggered the recommendation. Inferred from §7: AI MAY recommend transitions; staff must confirm.
• Stack & stage filter bar — a persistent filter control above the pipeline list allowing filtering by Stack, stage, BookingEligibility, owner, source channel, and SLA status. Inferred from §14.4.
• Saved view selector — a control for switching between "Booking Ready", "Emergency", and "My Pipeline" saved views, and for any staff-created saved views. Inferred from §14.4.
• Proposal state badge — a read-only badge on the linked Opportunity detail view displaying the current Smart Treatment Proposal state (Draft, Presented, Explained & Acknowledged, Accepted, Declined, or Expired). Used to communicate whether a ProposalAccepted-driven pipeline advance is legitimate and to block advance actions when the proposal is not in the Accepted state. Inferred from STP technical spec §3.2 and Flow 3 (§5.1).

Reused from the design system:

• Form fields and labels (triage artefact editing)
• Date/time picker (deferred Opportunity review date)
• Role/owner selector (owner assignment per record)
• Toast notification (stage transition confirmations, eligibility change confirmations)
• In-app banner (SLA breach alerts, Emergency Stack escalation alerts)
• Data table / list row
• Detail pane / split-pane layout shell
• Confirmation modal (base pattern, extended by stage transition confirmation modal above)

7. Visual Design Notes

• Typography: (needs UX writer input — heading scale, body scale, monospace usage to be confirmed against design system)
• Colour: Semantic colour usage must include a positive (green-semantic) state for Booking Permitted and Booked stages, an amber-semantic state for Awaiting Triage and at-risk SLA, a red-semantic state for SLA breached and Emergency Stack urgency, and a muted/grey state for Lost / Closed records. Inferred from §3.3 state machine and §4.3 Emergency Stack urgency requirements. Exact hex values are not specified here — defer to the design system.
• AI-attributed fields and suggestion cards must be visually distinct from staff-entered data. The specific visual treatment (e.g. border style, background tint, icon) is deferred to the design system, but the distinction must be unambiguous at a glance. Inferred from §7 and §8.1.
• Iconography: (needs UX writer input — icon set, sizing; icons must never appear without a visible label or accessible text equivalent)
• Motion: (needs UX writer input — transition usage; prefers-reduced-motion must be respected per §8)

8. Accessibility & Inclusivity

The module MUST meet WCAG 2.2 AA. Specifically:

• Text contrast ≥4.5:1 (normal) / ≥3:1 (large)
• All interactive controls reachable via keyboard
• Focus states visible
• Form fields have programmatic labels
• ARIA used only where native semantics are insufficient
• Touch targets ≥44×44 px on mobile/tablet
• Motion can be reduced via prefers-reduced-motion
• Screen reader tested on NVDA (Windows), VoiceOver (macOS/iOS), TalkBack (Android)

The pipeline stage badge and BookingEligibility gate indicator must not rely on colour alone to communicate state; they must also carry a text label or icon-with-label. Inferred from WCAG 1.4.1 (use of colour) and the clinical-context requirement that eligibility status be unambiguous.

The SLA countdown indicator must provide a text alternative for screen readers, not just a visual countdown bar. Inferred from WCAG 1.1.1 and the 72-hour Emergency Stack constraint in §4.3.

The AI attribution badge must be announced by screen readers so that assistive technology users know when data was AI-supplied rather than staff-entered. The announcement text should identify the AI channel. Inferred from §8.1 AI involvement marker requirements and governance-always-visible principle.

The proposal state badge (§6) must also be announced by screen readers with its current value, so that assistive technology users can confirm the proposal is in the Accepted state before acting on a pipeline advance. Inferred from STP technical spec §3.2 and the governance-always-visible principle.

(needs UX writer input — confirm screen reader testing matrix and any additional accessibility requirements from the practice environments where tablet app is deployed)

9. Internationalisation

• Locale-aware date/time/number formatting — particularly important for CreatedAt, ReviewDateUTC, SLA timestamps, and EstimatedValue currency display.
• All user-facing strings externalised; no hardcoded copy in components.
• Layouts tolerant of 30% string-length growth (German, French) — the pipeline stage badge, filter bar labels, and confirmation modal copy are all at risk of overflow; these components must use flexible layout, not fixed-width text containers.
• RTL support: not explicitly required by the technical spec; defer to platform-level RTL policy. (needs UX writer input — confirm whether RTL is required for any target market in scope for Post-MVP.)
• Stack names and Stage Template names are practice-configured strings (§14.3); the UI must handle variable-length, user-defined labels gracefully without truncating in ways that obscure meaning. Inferred from §4.1 and §14.3.

10. Cross-Module UX Touchpoints

Where this module's UX intersects with related modules:

• Communication Hub — the ConversationThreadID on every Lead and Opportunity is a direct link to the unified conversation timeline. In the Lead/Opportunity detail view, a "View conversation" action should surface the Communication Hub thread in context (e.g. as a side panel or a navigated view). The handoff is one-directional from pipeline to Communication Hub; Communication Hub does not navigate back to the pipeline. Inferred from §10.4 unified conversation thread contract.
• Appointment Manager — when a record reaches Booking Permitted, the pipeline detail view should surface a "Proceed to booking" action that hands off to Appointment Manager with the LeadID or OpportunityID and confirmed BookingEligibility. Appointment Manager owns slot selection; Treatment Pipeline Manager must not replicate diary UI. Inferred from §2.2, §5, and §10.2.
• AI Concierge — AI Concierge creates Leads via the governed intake endpoint and may supply triage summaries and stage-transition recommendations. These appear in the Lead record in the web portal and tablet app as AI-attributed data, with source-channel labelling as "AI Concierge (Voice)" (see also §5.4). Staff do not interact with AI Concierge directly through the pipeline UI; the touchpoint is the data AI Concierge deposits. Inferred from §10.3 and §7.
• Aiden — Aiden creates Leads from website conversational intake. Like AI Concierge, the touchpoint is the AI-attributed data visible on the Lead record. Inferred from §10.1 and §3.1 SourceChannel enum.
• Smart Treatment Proposals — when a ProposalAccepted event drives a stage transition, the resulting Opportunity detail view must display the current proposal state badge (see §6) and label the transition as "Triggered by accepted proposal" with the ProposalID visible for reference. The proposal state badge must reflect live proposal state (Accepted, Declined, Expired, etc.) so that staff can verify correctness before or during a pipeline advance. A "View proposal" link is desirable but the proposal UI is owned by Smart Treatment Proposals. Inferred from §3.3.1, §8.1 audit event for ProposalAccepted, and STP technical spec §3.2.
• Task Manager — Task Manager generates staff follow-up tasks from pipeline triggers (next-action and SLA breach events). The pipeline UI should surface the existence of open tasks on a record (e.g. a task count badge on the record card) without duplicating Task Manager's task management UI. Inferred from §10.2 outbound to Task Manager and §14.2 rule 7.
• Campaign Manager — Campaign Manager consumes segmentation events but does not write back to the pipeline. There is no direct UX touchpoint in the pipeline UI; the connection is event-based and invisible to the staff user. Inferred from §8.2 and §10.2.
• Audit & Compliance — the audit log export action (Admin only) in the web portal is the visible UX surface for the pipeline's audit event stream. The audit log itself is owned and rendered by Audit & Compliance; the pipeline UI exposes a navigable link or export trigger. Inferred from §8.3, §9 Export audit log permission, and §10.2.
• Access Manager — the current user's role and active permissions must be visible in the portal header, and role-controlled actions (e.g. Set BookingEligibility, Configure Stacks) must be hidden or disabled for users without the required role. Role names displayed in the UI must match the canonical names from Access Manager. Inferred from §9 and the governance-always-visible principle.

UX consistency rules:

• Action buttons for irreversible governed actions (Set BookingEligibility, Close record, Advance stage past Booking Permitted) must be visually distinct from routine actions — not by colour alone, but by position, label weight, or an additional confirmation affordance. Inferred from the governance-always-visible principle and §3.3 irreversibility rules.
• AI attribution badges must use the same visual language and placement across all contexts in which AI-supplied data appears (triage summary, stage recommendation, ProposalAccepted-driven transition). Inferred from §7 and §8.1.
• The ConversationThreadID link must be presented consistently — same label, same icon, same position in the detail view — for both Leads and Opportunities, so staff learn a single interaction pattern for accessing the conversation timeline. Inferred from §10.4.

11. Governance & Auditability

• AI-supplied fields (triage summary from AI Concierge or Aiden, stage-transition recommendations) are visually distinct from staff-entered data using an AI attribution badge that names the originating AI channel. Inferred from §7 and §8.1 AI involvement markers.
• Stage transitions driven by a ProposalAccepted event are labelled in the record's activity/audit timeline with "Triggered by accepted proposal" and the ProposalID, so staff can trace the automation without opening the audit log. Inferred from §3.3.1 AuditTrail requirement with Trigger = ProposalAccepted.
• All audit-significant actions — setting BookingEligibility = true, advancing to Booking Permitted or beyond, closing a record — show a confirmation step that names the action, the actor, and (where applicable) the irreversibility of the transition. Inferred from §8.1 and §14.2 rule 6.
• The current user's role is visible in the portal header. Role-gated controls (e.g. "Set booking eligible", "Configure stacks") are hidden from roles that do not hold the required permission; they are not shown as disabled, to avoid confusion. Inferred from §9 access control table and the no-dead-toggles principle.
• Read-only fields (such as EstimatedValue, AI triage summary) are visually distinct from editable fields — typically rendered as display text rather than form inputs, with no edit affordance. Inferred from §3.2 and §7.
• The record's activity timeline (surfacing key audit events: creation, stage transitions, eligibility changes, booking attempts, segmentation events) must be accessible within the detail view, surfacing the actor identity and UTC timestamp for each event. This is a read-only view of the immutable audit trail; it does not allow editing. Inferred from §8.1 and §3.1 / §3.2 AuditTrail fields.
• Emergency Stack records carry a persistent visual urgency marker throughout their lifetime, and the 72-hour countdown is always visible on the record card and detail view. Inferred from §4.3 and the governance-always-visible principle.

12. Notification & Communication Patterns

• In-app banner — used for SLA breach alerts (a Lead or Opportunity has breached its Stack SLA threshold) and Emergency Stack escalation alerts (record approaching or past the 72-hour limit). Banners are persistent until the condition is resolved or the record is actioned. Inferred from §4.3 Emergency Stack SLA contract and §14.2 rule 7.
• Toast — used for confirmation of completed actions: stage transition committed, BookingEligibility changed, record closed, triage artefact saved. Toasts are transient (auto-dismiss after a short interval) and must not be used for urgent or actionable alerts. Inferred from the calm-by-default principle and the confirmation requirements in §8.1.
• Push notification (via Communication Hub) — stage-change notifications that may trigger patient-facing messaging are delivered via Communication Hub, not directly by the pipeline module. From the staff UX perspective, the pipeline UI surfaces a record of that Communication Hub event in the activity timeline, but does not itself send push notifications to staff devices. Inferred from §10.2 outbound to Communication Hub and §6.4 engagement signals.
• Email/SMS (via Communication Hub) — any patient-facing or staff-facing email or SMS triggered by a pipeline event (e.g. a follow-up message after a stage change) is executed by Communication Hub based on pipeline events. The pipeline UI does not compose or send messages directly. Inferred from §2.2 (message delivery owned by Communication Hub) and §10.2.
• Task Manager notifications — next-action and SLA breach triggers emitted by the pipeline are consumed by Task Manager, which is responsible for surfacing follow-up tasks to staff. The pipeline UI shows a task-count indicator on records with open tasks but defers the task management UX to Task Manager. Inferred from §6.4 engagement signals and §10.2 outbound to Task Manager.

13. Open Questions

The following UX decisions must be resolved before this spec is promoted from draft to published.

1. Patient-facing surface scope confirmation — the technical spec §6.3 explicitly states no patient-facing surface, but §4.3 Mobile App section above notes this should be formally confirmed for Post-MVP. Is a lightweight staff-mobile read view in scope? (Inferred from §6.3 and §4.3 above.)
2. "View conversation" handoff UX — when a staff member selects the ConversationThreadID link on a Lead or Opportunity, does this open Communication Hub in a side panel within the pipeline UI, navigate to a separate Communication Hub screen, or open in a new tab? The interaction pattern has significant implications for the split-pane layout. (Inferred from §10.4 unified conversation thread contract.)
3. "View proposal" handoff UX — when a ProposalAccepted-driven transition is displayed in the activity timeline, should the ProposalID link navigate into Smart Treatment Proposals? If so, what is the return journey back to the pipeline record? (Inferred from §3.3.1.)
4. Task count badge on pipeline cards — should open Task Manager tasks be surfaced as a count badge on each Lead/Opportunity card in the list view? If yes, does clicking the badge navigate to Task Manager, or open an inline task preview? (Inferred from §10.2 outbound to Task Manager.)
5. AI suggestion card dismissal — when a staff member dismisses an AI-recommended stage transition, is the dismissal logged to the audit trail (as a rejected AI suggestion)? The technical spec §8.1 requires logging of AI involvement markers including whether suggestions were accepted or rejected; the UX must support this. (Inferred from §8.1.)
6. LostReason field design — is LostReason a free-text field, a constrained enum (practice-configured), or a hybrid? This affects the design of the stage transition confirmation modal for Lost / Closed. The technical spec names the field in the segmentation event payload but does not define its input type. (Inferred from §8.2 OpportunityLost event.)
7. EstimatedValue display — EstimatedValue is read-only and system-derived, but the technical spec §16 open question 5 notes that the source of this value is unresolved. The UX must decide whether to display the field when its value is null/unavailable, and what label or tooltip to show. (Mirrors technical spec open question 5 in §16.)
8. Stack configuration UI placement — the Admin Control Plane is referenced in §14.3 as the surface for Stack and Stage Template configuration. Is this a separate admin module with its own navigation, or an embedded section within the Treatment Pipeline Manager web portal? This affects navigation architecture. (Inferred from §14.3.)
9. Aiden intake contract UX implications — the technical spec §16 open question 6 notes that the Aiden intake endpoint contract is undefined. Until this is resolved, the UX cannot fully specify how Aiden-sourced Leads are attributed and displayed differently (if at all) from AI Concierge-sourced Leads. (Mirrors technical spec open question 6.)
10. Retention and GDPR deletion UX — when a Lead or Opportunity record is subject to a data subject deletion request, what does the pipeline UI show in place of the deleted record? A tombstone entry? A redacted record? This depends on the retention period decision (technical spec open question 1 in §16), but the UX pattern must be designed. (Inferred from §8.3 and §15 privacy requirements.)
11. Proposal state live-update behaviour — when the linked Smart Treatment Proposal changes state (e.g. from Presented to Accepted, or from Accepted to Expired) while the Opportunity detail view is open, should the proposal state badge update in real time (via websocket or polling), or only on page reload? The answer affects whether a staff member could act on a stale proposal state. (Inferred from STP technical spec §3.2 and §5.4 urgency signal propagation.)
12. Out-of-hours intake labelling source — the "Out-of-hours intake" label on AI Concierge-sourced Leads (§5.4) requires knowledge of the practice's configured working hours. Confirm whether this configuration is available to the pipeline module directly, or whether the out-of-hours flag must be derived from intake timestamp comparison alone. (Inferred from §5.4 and AI Concierge module specification.)
13. (needs UX writer input — exact microcopy for all confirmation modals, empty states, AI attribution badges, SLA alert banners, and toast notifications)