local-pocket-screen-flow-pass · supabase_json
PVA Local Pocket App Screen Flow Pass
local-pocket-screen-flow-pass artifact · for Patient Visit Advocate · phase PVA-SLICE-01 · status approved
screens
| id | name | slug | layout | states | trigger |
|---|---|---|---|---|---|
| S-00 | Draft Recovery | draft.recovery | Centered card on pva-surface-page. Single focused decision. No navigation chrome. Card max-width 480px, centered vertically at 40% viewport height. | - default (draft found) - discard_confirm_expanded | On app open: check localStorage for draft object with status in [draft_created, intake_started, intake_reviewed, brief_ready, question_plan_ready, visit_notes_started]. If found and not expired, show this screen before anything else. |
| S-01 | Fast Visit Start | visit.start.fast | Full-screen, no persistent nav chrome. Single column. Logo/wordmark top-left at 32px, pva-text-secondary. Center content area begins at 20% from top. Maximum content width 480px centered. One-hand reachable: primary CTA in bottom 25% of screen. | - empty (no reason) - reason_entered | |
| S-02 | Messy Intake Capture | intake.capture | Full-screen, minimal chrome. Top: back chevron (left) + step indicator text 'Step 1 of 4: Tell us what is going on' (right). Content: large free-text area filling most of viewport. Bottom: progress-aware CTA anchored at bottom. Maximum comfortable width 600px. | - empty - typing - ready_to_submit - submitting_online - submitting_offline_manual - escalation_triggered | |
| S-ESC | Safety Escalation Acknowledgement | safety.escalation.ack | Full-screen overlay on top of whatever screen triggered it. pva-surface-page background. Center card, max-width 480px. Cannot be swiped or tapped away. Only two exits: acknowledge or call emergency services. | - default (visible, hard-stop) | |
| S-03 | Editable Intake Review | intake.review.local | Full-screen scroll. Top: back chevron + 'Step 2 of 4: Review your notes'. Sections stack vertically separated by pva-border-subtle dividers. Each section has an inline Edit button. Bottom: sticky CTA bar. | - ai_extracted - manual_mode - editing_section - generating_brief (loading overlay) - ai_failure_on_retry | |
| S-04 | Visit Brief | visit.brief.local | Full-screen scroll. Print-like layout. Top: back chevron + 'Your visit brief'. Content: single-column brief sections. No dense dashboard layout. Max reading width 680px centered. Top-right: Export button (icon + label). Bottom: sticky CTA bar. | - ai_generated - stub_manual - editing_section - loading_questions | |
| S-05 | Question Plan | question.plan.local | Full-screen scroll. Top: back chevron + 'Your question plan'. Content: prioritized question list. Max reading width 680px. Top-right: Export button. Bottom: sticky CTA bar. | - ai_generated - stub_manual - in_progress_marking - all_answered - loading | |
| S-06 | Quick Note / Mark Answered | visit.live.note | Minimal chrome. One-hand first: primary actions (mark answered, add note) in bottom 35% of screen. Top: 'In your appointment' label + minimalist session timer (optional). Question list scroll area fills middle of screen. Fixed bottom note bar. | - active_appointment - all_questions_answered - end_confirm | |
| S-07 | Post-Visit Quick Capture | post.visit.quick.capture | Full-screen scroll. Top: 'Step 3 of 4: After your visit'. Warm, low-pressure tone. Single scrolling form with grouped sections. Bottom: sticky CTA bar. | - empty - in_progress - generating_debrief - escalation_triggered | |
| S-08 | Export Confirmation | export.confirm.local | Bottom sheet slides up over current screen. pva-surface-panel background. Max-height 70% viewport. Rounded top corners 12px. Drag handle at top center. | - pre_export - export_in_progress - post_export_success - post_export_memory_prompt | |
| S-DELETE | Draft Delete Confirmation | draft.delete | Bottom sheet. Minimal. Single confirmation. | - default - deleting |
flows
| id | name | type | steps | precondition | estimated time |
|---|---|---|---|---|---|
| FL-00 | Happy Path: First-time waiting-room user | happy_path | - S-01 (Fast Visit Start) - S-02 (Intake Capture) - S-03 (Editable Review) - S-04 (Visit Brief) - S-05 (Question Plan) - S-06 (Quick Note, in appointment) - S-07 (Post-Visit Capture) - S-08 (Export Confirmation, export) | No existing draft. App launch. | 15-25 minutes total across visit day |
| FL-01 | One-hand waiting-room fast path | accelerated_path | - S-01 (skip reason, tap Start now) - S-02 (type messy intake fast) - S-03 (quick scan review, minimal edits) - S-04 (scan brief, skip to questions) - S-05 (review question plan) | No draft. User has 3-5 minutes. | |
| FL-02 | Draft recovery: returning user | recovery_path | - S-00 (Draft Recovery modal) - continue_draft: resumes at last state in local_state_machine - discard_draft (with inline confirm): S-01 fresh | Unfinished local draft exists on device. | |
| FL-03 | Escalation: serious symptom mid-intake | safety_path | - S-02 (intake, safety signal detected) - submit: S-ESC (Safety Escalation Acknowledgement, hard stop) - acknowledge: S-03 (continue normal flow) | User enters serious-symptom signal during S-02 intake. | |
| FL-04 | AI failure: manual fallback | fallback_path | - S-02 or S-03: AI fails, inline error shown, user taps 'Continue manually' - S-03-manual mode (all fields empty, user fills) - S-04-stub mode (brief sections empty, user fills) - S-05-stub mode (questions empty or basic defaults, user adds) | AI extraction or brief generation fails at any point. | |
| FL-05 | Offline session | offline_path | - Any screen: offline banner shown (not blocking) - S-02: intake capture works fully - S-03: manual mode auto-engaged if AI not available - S-04: stub mode auto-engaged if brief generation requires model - S-05: question list empty or defaulted; user can add custom - S-06: fully offline - S-07: fully offline - S-08: text copy export works; PDF/share sheet noted as device-dependent | Device has no network signal at any step. | |
| FL-06 | Export only: user wants to show brief in appointment | shortcut_path | - S-04: tap Export button - S-08 (Export Confirmation) - Choose 'Share via device sheet' or 'Copy as text' - Return to S-04 or S-05 | User completes brief (S-04) and wants to show/share immediately. | |
| FL-07 | Delete draft | destructive_path | - Overflow menu on S-03, S-04, or S-05: 'Delete this draft' - S-DELETE (bottom sheet confirm) - confirm: S-01 (fresh) - cancel: return to screen | User wants to remove a draft at any point. |
open questions
| id | affects | context | question | my default |
|---|---|---|---|---|
| OQ-01 | prototype build planning | A keyword list is simpler, faster to prototype, and avoids any model call risk. A local model is more accurate but adds prototype complexity. The trust boundary charter requires no cloud call with health text. | Should the serious-symptom signal detection in S-02 and S-07 use a hardcoded keyword list or a local-only client ML model? | Keyword list for SLICE-01 prototype. Escalation to model detection is a SLICE-05 decision. |
| OQ-02 | prototype build scope | The prototype spec says voice can be simulated or deferred. This affects whether the build team needs to integrate any transcription API or can leave it as a non-functional affordance. | Is voice input in S-02 a stubbed interaction (shows placeholder transcript) or fully deferred in the prototype? | Fully deferred for SLICE-01 prototype — microphone icon present, tapping shows 'Voice input coming soon' toast. No transcription API needed. |
| OQ-03 | prototype build planning | ES-09 documents the post-expiry state. Should the app warn the user before expiry (e.g. at 25 days with a banner) or silently remove at 30 days? The prototype spec says 30 days recommended but does not specify pre-expiry warning. | What is the exact trigger threshold for the 30-day draft expiry notice vs. silent removal? | Silent removal at 30 days for prototype. Pre-expiry warning is a production polish feature. |
Agent Handoff
Start Here
local-pocket-screen-flow-pass artifact · for Patient Visit Advocate · phase PVA-SLICE-01 · status approved
Completion Evidence
No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.
Open Questions
- OQ-01: id: string, affects: string, context: string, question: string, my_default: string
- OQ-02: id: string, affects: string, context: string, question: string, my_default: string
- OQ-03: id: string, affects: string, context: string, question: string, my_default: string
Structured Payload
Machine-readable source fields
flows
| id | name | type | steps | precondition | estimated time |
|---|---|---|---|---|---|
| FL-00 | Happy Path: First-time waiting-room user | happy_path | - S-01 (Fast Visit Start) - S-02 (Intake Capture) - S-03 (Editable Review) - S-04 (Visit Brief) - S-05 (Question Plan) - S-06 (Quick Note, in appointment) - S-07 (Post-Visit Capture) - S-08 (Export Confirmation, export) | No existing draft. App launch. | 15-25 minutes total across visit day |
| FL-01 | One-hand waiting-room fast path | accelerated_path | - S-01 (skip reason, tap Start now) - S-02 (type messy intake fast) - S-03 (quick scan review, minimal edits) - S-04 (scan brief, skip to questions) - S-05 (review question plan) | No draft. User has 3-5 minutes. | |
| FL-02 | Draft recovery: returning user | recovery_path | - S-00 (Draft Recovery modal) - continue_draft: resumes at last state in local_state_machine - discard_draft (with inline confirm): S-01 fresh | Unfinished local draft exists on device. | |
| FL-03 | Escalation: serious symptom mid-intake | safety_path | - S-02 (intake, safety signal detected) - submit: S-ESC (Safety Escalation Acknowledgement, hard stop) - acknowledge: S-03 (continue normal flow) | User enters serious-symptom signal during S-02 intake. | |
| FL-04 | AI failure: manual fallback | fallback_path | - S-02 or S-03: AI fails, inline error shown, user taps 'Continue manually' - S-03-manual mode (all fields empty, user fills) - S-04-stub mode (brief sections empty, user fills) - S-05-stub mode (questions empty or basic defaults, user adds) | AI extraction or brief generation fails at any point. | |
| FL-05 | Offline session | offline_path | - Any screen: offline banner shown (not blocking) - S-02: intake capture works fully - S-03: manual mode auto-engaged if AI not available - S-04: stub mode auto-engaged if brief generation requires model - S-05: question list empty or defaulted; user can add custom - S-06: fully offline - S-07: fully offline - S-08: text copy export works; PDF/share sheet noted as device-dependent | Device has no network signal at any step. | |
| FL-06 | Export only: user wants to show brief in appointment | shortcut_path | - S-04: tap Export button - S-08 (Export Confirmation) - Choose 'Share via device sheet' or 'Copy as text' - Return to S-04 or S-05 | User completes brief (S-04) and wants to show/share immediately. | |
| FL-07 | Delete draft | destructive_path | - Overflow menu on S-03, S-04, or S-05: 'Delete this draft' - S-DELETE (bottom sheet confirm) - confirm: S-01 (fresh) - cancel: return to screen | User wants to remove a draft at any point. |
phase
id
PVA-SLICE-01
name
Local-Only Pocket Prototype
status
draft
title
PVA Local Pocket App Screen Flow Pass
product
Patient Visit Advocate
purpose
Convert the approved local-only pocket prototype spec into a precise screen-and-state flow that prototype build work can execute from directly. Surfaces before flows. States before transitions. No implementation code.
screens
| id | name | slug | layout | states | trigger |
|---|---|---|---|---|---|
| S-00 | Draft Recovery | draft.recovery | Centered card on pva-surface-page. Single focused decision. No navigation chrome. Card max-width 480px, centered vertically at 40% viewport height. | - default (draft found) - discard_confirm_expanded | On app open: check localStorage for draft object with status in [draft_created, intake_started, intake_reviewed, brief_ready, question_plan_ready, visit_notes_started]. If found and not expired, show this screen before anything else. |
| S-01 | Fast Visit Start | visit.start.fast | Full-screen, no persistent nav chrome. Single column. Logo/wordmark top-left at 32px, pva-text-secondary. Center content area begins at 20% from top. Maximum content width 480px centered. One-hand reachable: primary CTA in bottom 25% of screen. | - empty (no reason) - reason_entered | |
| S-02 | Messy Intake Capture | intake.capture | Full-screen, minimal chrome. Top: back chevron (left) + step indicator text 'Step 1 of 4: Tell us what is going on' (right). Content: large free-text area filling most of viewport. Bottom: progress-aware CTA anchored at bottom. Maximum comfortable width 600px. | - empty - typing - ready_to_submit - submitting_online - submitting_offline_manual - escalation_triggered | |
| S-ESC | Safety Escalation Acknowledgement | safety.escalation.ack | Full-screen overlay on top of whatever screen triggered it. pva-surface-page background. Center card, max-width 480px. Cannot be swiped or tapped away. Only two exits: acknowledge or call emergency services. | - default (visible, hard-stop) | |
| S-03 | Editable Intake Review | intake.review.local | Full-screen scroll. Top: back chevron + 'Step 2 of 4: Review your notes'. Sections stack vertically separated by pva-border-subtle dividers. Each section has an inline Edit button. Bottom: sticky CTA bar. | - ai_extracted - manual_mode - editing_section - generating_brief (loading overlay) - ai_failure_on_retry | |
| S-04 | Visit Brief | visit.brief.local | Full-screen scroll. Print-like layout. Top: back chevron + 'Your visit brief'. Content: single-column brief sections. No dense dashboard layout. Max reading width 680px centered. Top-right: Export button (icon + label). Bottom: sticky CTA bar. | - ai_generated - stub_manual - editing_section - loading_questions | |
| S-05 | Question Plan | question.plan.local | Full-screen scroll. Top: back chevron + 'Your question plan'. Content: prioritized question list. Max reading width 680px. Top-right: Export button. Bottom: sticky CTA bar. | - ai_generated - stub_manual - in_progress_marking - all_answered - loading | |
| S-06 | Quick Note / Mark Answered | visit.live.note | Minimal chrome. One-hand first: primary actions (mark answered, add note) in bottom 35% of screen. Top: 'In your appointment' label + minimalist session timer (optional). Question list scroll area fills middle of screen. Fixed bottom note bar. | - active_appointment - all_questions_answered - end_confirm | |
| S-07 | Post-Visit Quick Capture | post.visit.quick.capture | Full-screen scroll. Top: 'Step 3 of 4: After your visit'. Warm, low-pressure tone. Single scrolling form with grouped sections. Bottom: sticky CTA bar. | - empty - in_progress - generating_debrief - escalation_triggered | |
| S-08 | Export Confirmation | export.confirm.local | Bottom sheet slides up over current screen. pva-surface-panel background. Max-height 70% viewport. Rounded top corners 12px. Drag handle at top center. | - pre_export - export_in_progress - post_export_success - post_export_memory_prompt | |
| S-DELETE | Draft Delete Confirmation | draft.delete | Bottom sheet. Minimal. Single confirmation. | - default - deleting |
created at
2026-05-08T17:39:00.000Z
created by
zara
hard stops
| id | bypass | reason | screen |
|---|---|---|---|
| HS-01 | false | Draft recovery choice must be explicit — no silent overwrite of existing draft. | S-00 |
| HS-02 | false | TB-002: Serious symptom acknowledgement required before continuing normal prep. Escape key disabled. | S-ESC |
| HS-03 | false | Two-step confirm required for destructive delete. Cancel is the default focus. | S-DELETE |
project id
31d7f681-bed2-44e9-9a55-b9fadcbba0da
artifact type
local-pocket-screen-flow-pass
open questions
| id | affects | context | question | my default |
|---|---|---|---|---|
| OQ-01 | prototype build planning | A keyword list is simpler, faster to prototype, and avoids any model call risk. A local model is more accurate but adds prototype complexity. The trust boundary charter requires no cloud call with health text. | Should the serious-symptom signal detection in S-02 and S-07 use a hardcoded keyword list or a local-only client ML model? | Keyword list for SLICE-01 prototype. Escalation to model detection is a SLICE-05 decision. |
| OQ-02 | prototype build scope | The prototype spec says voice can be simulated or deferred. This affects whether the build team needs to integrate any transcription API or can leave it as a non-functional affordance. | Is voice input in S-02 a stubbed interaction (shows placeholder transcript) or fully deferred in the prototype? | Fully deferred for SLICE-01 prototype — microphone icon present, tapping shows 'Voice input coming soon' toast. No transcription API needed. |
| OQ-03 | prototype build planning | ES-09 documents the post-expiry state. Should the app warn the user before expiry (e.g. at 25 days with a banner) or silently remove at 30 days? The prototype spec says 30 days recommended but does not specify pre-expiry warning. | What is the exact trigger threshold for the 30-day draft expiry notice vs. silent removal? | Silent removal at 30 days for prototype. Pre-expiry warning is a production polish feature. |
design system ref
studio/pva/PVA-SLICE-01/pva-advocacy-ops-design-system.md
decisions embedded
| id | decision |
|---|---|
| D-001 | Visual language is PVA Advocacy Ops system, not Dreamborn brand tokens. pva-action-primary teal (#287C8E) is the primary interaction color. |
| D-002 | All primary CTAs are bottom-anchored for one-hand waiting-room usage. Minimum 48px touch height. |
| D-003 | AI failure at any step never blocks the user. Manual fallback is always available. |
| D-004 | Non-coercive memory prompt appears only in S-08 post-export success state. Never before. Never as a paywall. |
| D-005 | Three hard stops only: draft recovery choice (S-00), escalation acknowledgement (S-ESC), delete confirm (S-DELETE). No other blocking modals. |
| D-006 | Draft retention disclosed in S-01 footer. 30-day expiry. User-initiated delete available at any screen via overflow menu. |
visual language anchor
PVA Advocacy Ops: warm, supportive, calm under pressure. pva-surface-page background (#FAF8F4), pva-action-primary teal (#287C8E), pva-status-blocked red (#B94A48) reserved for escalation and hard stops only. Inter/Source Sans 3 for all UI text. No Dreamborn crimson, no gradient text, no side-stripe borders.
qa gate cross reference
| gate | note | screens |
|---|---|---|
| QA-001 | Brief, question plan, and debrief must not produce diagnosis or treatment instructions. Safety footer persistent in S-04. | - S-04 - S-05 - S-07 |
| QA-002 | S-ESC covers all escalation trigger surfaces: S-02, S-06, S-07. Hard stop confirmed. | - S-ESC |
| QA-003 | Draft recovery from S-00 restores state by local_state_machine entry. | - S-00 |
| QA-004 | Retention rule disclosed in S-01 footer. Delete confirmed in S-DELETE. Export metadata visible in S-08. | - S-01 - S-08 - S-DELETE |
| QA-005 | Export Confirmation sheet with explicit disclosure required before every export action. | - S-08 |
| QA-006 | Manual fallback path documented in ES-02, ES-03, ES-05 for each AI-dependent step. | - S-02 - S-03 - S-04 - S-05 |
| QA-007 | No server calls in local prototype. AI call stubs or device-local only. No health text to analytics. | - all |
empty offline failure states
| id | state | context | treatment | tokens |
|---|---|---|---|---|
| ES-01 | empty_start | No active draft (S-01 first launch) | S-01 shows full form. No list to be empty. No empty state needed here. | |
| ES-02 | ai_failure | AI extraction failed after S-02 submit | Inline error below textarea: 'We could not organize your notes. Continue manually or try again.' Two buttons: 'Try again' (if online) and 'Continue manually' (always). Raw input preserved in text area. Draft saved before attempt. | pva-status-review amber banner, pva-body error copy |
| ES-03 | ai_failure | Brief generation failed (S-03 → S-04) | Inline error in S-03 sticky bar area: 'We could not generate your brief. You can write it yourself.' S-04 stub mode opens with empty sections and editing active. Retry button shown if online. | pva-status-review amber |
| ES-04 | offline_mode | Offline: user in S-02 or S-03 | Non-blocking offline indicator at top of screen (pva-status-review amber dot + 'No connection — your notes are saved here'). Manual mode auto-engaged when continuing offline. No gate or hard stop. | pva-status-review, pva-meta size |
| ES-05 | ai_failure_stub | S-05 question plan — AI questions unavailable | pva-status-review amber banner: 'We could not generate questions automatically.' List shows empty state with Add custom question prompt active. User can add their own. Retry if online. | pva-status-review |
| ES-06 | empty_extraction | S-03 all sections empty (AI extracted nothing meaningful) | All sections show pva-text-muted 'Not detected — tap to add' placeholder. No error banner needed unless AI explicitly failed. User proceeds to fill manually or edits. | pva-text-muted, pva-meta |
| ES-07 | ai_failure | S-07 post-visit capture — AI debrief fails | Inline: 'We saved your notes. You can export them now.' Primary CTA changes to 'Export raw notes'. Raw field values are preserved and included in export. | pva-status-review, pva-body |
| ES-08 | export_partial | S-08 export — PDF unavailable (offline or browser restriction) | PDF option shown with '(not available right now)' label in pva-text-muted. Text copy and device share sheet options remain. No hard stop. | pva-text-muted |
| ES-09 | draft_expired | Draft expired (30 days elapsed) | If S-00 recovery modal opens for an expired draft: show 'This visit draft expired on [date] and was removed.' Single CTA: 'Start a new visit'. No option to recover. | pva-text-secondary body, pva-meta date |
one hand waiting room behavior
principles
- All primary CTAs bottom-anchored with space-6 (24px) bottom margin minimum.
- Minimum tap target 44px height, 48px preferred for primary actions.
- No required two-finger gesture at any step in the free loop.
- Scroll region always between top chrome and bottom CTA bar — never full-viewport scroll with floating CTA.
- S-06 (live note) is the highest-stakes one-hand surface — bottom note bar and large row tap targets are mandatory, not optional.
session timer
S-06 may show a minimalist elapsed timer (pva-text-muted, pva-meta). Non-blocking, non-animated.
voice input surface
S-02 only in prototype. Voice toggle is supplementary, not required.
non coercive memory prompt rules
location
S-08 (Export Confirmation) only — post-export success state, never before export completes.
dismissal
'No thanks' link dismisses permanently (localStorage flag). Never re-shown after dismissal.
copy rules
- Never imply the current visit will be lost without upgrading.
- Never show before the user completes a successful action.
- Frame as future benefit, not current loss.
- No countdown timers, urgency language, or 'before you go' pressure patterns.
visual weight
Text link CTA, not button. pva-action-primary text color. pva-surface-subtle background. Positioned after export confirmation success message.
trust boundary ref
monetization_boundary.caution: Do not punish the free user immediately after trust is earned.