feature-ux-spec · supabase_json
Patient Visit Advocate feature-ux-spec MVP-01
feature-ux-spec artifact · for Patient Visit Advocate · phase MVP-01 · status approved
open questions
| id | owner | blocks | question |
|---|---|---|---|
| OQ-03 | justin | Production AI implementation and vendor review | Which model/provider path will satisfy health-sensitive data handling, retention, and logging constraints? |
| OQ-04 | justin | Public launch beyond internal prototype | Who reviews the first safety copy and escalation patterns before public launch? |
| OQ-05 | justin | Caregiver screens and permission flows | Should full caregiver access be included in MVP UI or only represented in the data model for paid-plan readiness? |
| OQ-06 | justin | Storage implementation and deletion policy | What is the default retention period for raw intake/raw debrief notes after structured confirmation? |
| OQ-07 | justin | MVP release boundary and implementation sequencing | Which first-release screens must ship before any private user pilot: strict first_release_minimum only, or family_plan_minimum as well? |
| UX-OQ-QNA-001 | Should public MVP navigation lead with Q&A library, visit-prep loop, or a blended Prepare / Learn / Review model? |
Agent Handoff
Start Here
feature-ux-spec artifact · for Patient Visit Advocate · phase MVP-01 · status approved
Completion Evidence
| id | criterion |
|---|---|
| UX-AC-QNA-001 | Q&A card screenshot shows exact disclaimer footer visible while card is expanded on desktop and mobile; footer is not dismissible. |
| UX-AC-QNA-002 | Onboarding cannot be bypassed before acknowledgement; acknowledgement records disclaimer version/timestamp. |
| UX-AC-QNA-003 | Coverage cluster screen renders exact recency caveat and can collapse only after reading. |
| UX-AC-QNA-004 | No Q&A UI labels use What to do or ask. |
| UX-AC-QNA-005 | Review queue exposes lint finding categories and blocks publishing flagged rows until reviewed. |
Open Questions
- OQ-03: id: string, owner: string, blocks: string, question: string
- OQ-04: id: string, owner: string, blocks: string, question: string
- OQ-05: id: string, owner: string, blocks: string, question: string
- OQ-06: id: string, owner: string, blocks: string, question: string
- OQ-07: id: string, owner: string, blocks: string, question: string
- UX-OQ-QNA-001: id: string, question: string
Structured Payload
Machine-readable source fields
phase
id
MVP-01
name
Prepared Visit Loop
status
draft
features
| id | ux | name | priority | functional |
|---|---|---|---|---|
| F-01 | - flows: 1 item - platform: both - surfaces: 1 item - design tokens: 3 items - open questions: 0 items | Conversational Intake | P0 | - why: Patients cannot reliably pre-structure medical concerns under stress. - today: The idea has no intake product yet. - target: User answers adaptive plain-language prompts; system extracts structured symptoms, timeline, concerns, context, and unknowns. - done when: 3 items - scenarios: 1 item - constraints: 3 items - error states: 1 item - out of scope: 2 items |
| F-02 | - flows: 1 item - platform: both - surfaces: 2 items - design tokens: 2 items - open questions: 0 items | Visit Brief and Question Plan | P0 | - why: The core value moment is walking into the appointment prepared. - today: Patients rely on memory or generic lists. - target: System generates a concise visit brief and prioritized questions grounded in the user’s intake. - done when: 3 items - scenarios: 1 item - constraints: 2 items - error states: 1 item - out of scope: 1 item |
| F-03 | - flows: 1 item - platform: both - surfaces: 1 item - design tokens: 2 items - open questions: 0 items | Post-Visit Debrief | P1 | - why: Patients often forget instructions and fail to track unclear items after the appointment. - today: No debrief product exists. - target: User adds notes after visit; system organizes what happened, next steps, tests/referrals, monitoring, and unresolved questions. - done when: 3 items - scenarios: 1 item - constraints: 2 items - error states: 1 item - out of scope: 2 items |
decisions
| id | decision | rationale |
|---|---|---|
| D-001 | V1 is mobile-first responsive web/PWA, not native mobile. | Gets the prepared-visit loop into users’ hands fastest while preserving mobile appointment usage patterns. |
| D-002 | Anonymous local-only draft prep is allowed before account creation only if no server persistence or model request containing health content occurs before explicit consent. | Reduces signup friction while keeping sensitive health data handling explicit. |
screen map
note
Use design-002 for all production screen planning. design-001 is retained as original intake snapshot only.
phase id
design-002
artifact type
screen-map
cross cutting
auth pattern
Mobile-first responsive web/PWA. Anonymous local-only draft allowed before account creation only if sensitive health text is not sent to server/model and expires locally; account plus affirmative express consent required before storing history or generating with server-side AI.
data contracts
Visit
id, patient_profile_id, status, appointment_type, appointment_at_optional, clinician_or_location_optional, reason_label, created_at, updated_at
VisitBrief
id, visit_id, intake_summary_id, reason_for_visit, key_symptoms[], timeline_summary, context_summary, top_concerns[], clinician_clarifications[], safety_footer_copy_id
QuestionPlan
id, visit_id, visit_brief_id, primary_questions[], optional_questions[], question_header_copy_id
IntakeSummary
id, visit_id, raw_input_ref, symptoms[], timeline[], concerns[], current_context[], tried_already[], unknowns[], safety_flags[], user_confirmed_at
PatientProfile
id, owner_user_id, display_name, relationship_to_owner, baseline_context, medications_context, created_at, updated_at
CaregiverAccess
id, patient_profile_id, granted_to_user_id, role, permissions, status, created_at, revoked_at
PostVisitDebrief
id, visit_id, raw_notes_ref, what_happened, decisions[], tests_or_referrals[], next_steps[], monitor_items[], unanswered_questions[]
PatientMemoryItem
id, patient_profile_id, source_visit_id_optional, category, content, confidence_source, active, created_at, updated_at
error envelope
{ code, message, safe_user_message, retryable }loading pattern
Show progressive generation status: organizing intake, drafting brief, prioritizing questions.
empty state pattern
Start with one upcoming visit and a plain-language prompt: What is this appointment for?
design tokens
- calm healthcare-neutral palette
- large readable type
- legal/disclaimer text no smaller than 11px rendered on mobile
- info banners for coverage caveats, not warning styling
open questions
| id | owner | blocks | question |
|---|---|---|---|
| OQ-03 | justin | Production AI implementation and vendor review | Which model/provider path will satisfy health-sensitive data handling, retention, and logging constraints? |
| OQ-04 | justin | Public launch beyond internal prototype | Who reviews the first safety copy and escalation patterns before public launch? |
| OQ-05 | justin | Caregiver screens and permission flows | Should full caregiver access be included in MVP UI or only represented in the data model for paid-plan readiness? |
| OQ-06 | justin | Storage implementation and deletion policy | What is the default retention period for raw intake/raw debrief notes after structured confirmation? |
| OQ-07 | justin | MVP release boundary and implementation sequencing | Which first-release screens must ship before any private user pilot: strict first_release_minimum only, or family_plan_minimum as well? |
| UX-OQ-QNA-001 | Should public MVP navigation lead with Q&A library, visit-prep loop, or a blended Prepare / Learn / Review model? |
schema version
1.0
source artifacts
| id | artifact id |
|---|---|
| client-source-reference | fb647c16-c6de-412b-a46f-56746971cf25 |
required surfaces
| id | job | title | required before |
|---|---|---|---|
| qna.cluster | List advocacy education questions by wave/cluster/category and show coverage caveat when applicable. | Q&A Cluster | public_qna_launch |
| qna.card | Show What to Know, Questions to Ask Your Provider, What to Watch For, and persistent disclaimer. | Q&A Card | public_qna_launch |
| legal.onboarding | Capture first-launch acknowledgement of app education/no-advice boundary. | Before You Start | any_content_access |
| settings.legal | Let users reread the disclaimer and education/no-advice boundary. | Legal | public_qna_launch |
| admin.qna.review | Let operators review import/lint findings before publishing content. | Q&A Review Queue | qna_ingestion_release |
acceptance criteria
| id | criterion |
|---|---|
| UX-AC-QNA-001 | Q&A card screenshot shows exact disclaimer footer visible while card is expanded on desktop and mobile; footer is not dismissible. |
| UX-AC-QNA-002 | Onboarding cannot be bypassed before acknowledgement; acknowledgement records disclaimer version/timestamp. |
| UX-AC-QNA-003 | Coverage cluster screen renders exact recency caveat and can collapse only after reading. |
| UX-AC-QNA-004 | No Q&A UI labels use What to do or ask. |
| UX-AC-QNA-005 | Review queue exposes lint finding categories and blocks publishing flagged rows until reviewed. |
global ux requirements
| id | exact text | requirement | headline | button label |
|---|---|---|---|---|
| UX-QNA-001 | General educational information only ? not medical advice. Always discuss your specific situation with your qualified healthcare provider. | Every expanded Q&A card displays the exact non-dismissible footer disclaimer. | ||
| UX-QNA-002 | First launch shows Before you start disclaimer and requires explicit acknowledgement before content access. | Before you start | I understand, let?s get started | |
| UX-QNA-003 | Settings > Legal exposes the same onboarding disclaimer text at any time. | |||
| UX-QNA-004 | Coverage clusters show the exact recency caveat as an info banner on cluster/category landing screens. | |||
| UX-QNA-005 | Q&A section label must be Questions to ask your provider; do not show What to do or ask. |