Skip to content

PROGRESSIVE_INTERVIEW_DESIGN_SPEC.md

Last updated: April 13, 2026 (Omega v2.7). Layer 4 build status UNVERIFIED — verify before launch.

Supersedes: - files/PROGRESSIVE_INTERVIEW_DESIGN_SPEC.md (Omega v2.2, March 26, 2026) - files/ADDENDUM_PROGRESSIVE_INTERVIEW_DESIGN_SPEC.md (Omega v2.3, March 26, 2026) - files/MANDATORY_INTERVIEW_PATCH.md (March 25, 2026) - files/DELTA_QUICK_CHECK_PROGRESSIVE_INTERVIEW.md - files/SPRINT_ALPHA_PROGRESSIVE_INTERVIEW.md - files/sprint_G3_trial_questionnaire.md (DEAD per v2.7 audit — 7-screen modal) - files/user_profiling_spec.md - files/alaivOS_dimensional_profiling_draft.md - all earlier profiling, dimensional-engine, and trial-questionnaire drafts

When any older doc disagrees with this file, THIS FILE WINS.

Cross-references: - TRIAL_AND_ONBOARDING.md — Day 0/14/28 Checkups, Day 14 phone verify, conversion - ANTI_ABUSE_SPEC.md — defense layer 3 (mandatory interview closes the "skip → free Elite" hole) - VOICE_AND_AI.md — PromptAssembler Layer 1 persona injection, ai_personas schema - CLAUDE.md — Ground Truth #11 (Interview mandatory, 45 questions, Days 1-14) - PRODUCT_SCOPE.md — Morning Pulse / Evening Wind Down delivery surfaces - PRICING_AND_TIERS.md — 21-day trial guarantee depends on interview completion


0. UNVERIFIED CLAIMS — VERIFY BEFORE LAUNCH

Per Omega v2.7 handover, these claims have not been reconfirmed against the live codebase this session. They were reported as BUILT by Gamma on March 26, 2026, but no re-audit has been performed after subsequent sprints (TAW waves, v2.6 call-system, v2.7 Checkup/AQ/Sports/Privacy).

Delta must re-verify each item below before launch and update this section.

Claim Source of record Verification needed
Layer 4 engine (progressive_interview_service.dart, 282 lines) is wired and firing Addendum March 26 Confirm file exists, provider registered, dashboard auto-init still active
45 questions in interview_question_bank.dart (24 A + 14 B + C templates + 7 D) Addendum March 26 Grep count, confirm enums match, no regressions
interview_card.dart rendered in prism_insight_card.dart and evening_wind_down_card.dart Addendum March 26 Confirm integration points still present post-v2.7 UI changes
Source D (7 fixed-day check-ins) fires on schedule Days 3/5/7/10/12/13/14 Spec §3 / Addendum Instrument test on a fresh trial simulation
markQuestionnaireCompleted() triggers proTrial → eliteTrial at 6/11 traits or Day 14 Spec §4.6 Confirm subscription_service wiring unchanged
31 tests in progressive_interview_test.dart still passing Addendum March 26 Run flutter test test/services/progressive_interview_test.dart
i18n fixes (5 ARB keys: interviewTypeAnswer, commonYes, commonNo, commonNotNow, commonDone) present across 21 locales Addendum March 26 ARB audit
Old G-3 trial_questionnaire_screen.dart (7-screen modal) marked @Deprecated and unreachable v2.7 TRIAL audit Confirm zero call sites; DEAD CODE
Old interview_screen.dart (27-question orphan) marked @Deprecated v2.7 TRIAL audit Confirm zero call sites

Until Delta signs off, treat Layer 4 as "likely built but not re-verified after v2.6 + v2.7." Do not assume the engine is firing without a fresh audit.


1. DESIGN PHILOSOPHY

The progressive interview is NOT a questionnaire. It is Laiv learning about the user through conversation, timed to moments when questions are relevant. It is:

  • Onboarding-aware — reads Day 0 answers to go deeper
  • Usage-aware — asks about features the user has actually tried
  • Respectful — max 2 questions per day, never interrupts, re-asks gracefully
  • Mandatory — Ground Truth #11. No skip button on profiling questions. Discovery nudges (Source C) alone can be deferred with "Not now."

Dual purpose: every question serves BOTH user profiling (feeds ai_personas → PromptAssembler Layer 1) AND product feedback (feeds analytics + improvement pipeline). No wasted interactions.

Delivery: in-app Laiv conversation prompts rendered as glass cards inside Morning Pulse, Evening Wind Down, and post-task moments. NOT a standalone questionnaire modal. NOT a 7-screen form. The old G-3 screen is DEAD CODE.


2. THE FOUR PROFILING LAYERS

Layer When What Exists?
1. Onboarding Day 0 Who you are (name, age, sex, goals, roadblock, style, currency) Built (NewOnboardingScreen, 8 questions). 6 fields now persisted to Supabase user_profiles for reinstall recovery (v2.7).
2. Guided Setup Day 0 How you want modules configured (2-3 per selected module) Built (guided_setup_screen.dart)
3. Passive Profiling Days 1+ What you actually do (module usage → cluster signals) Built (DimensionSignalCollector, ProfilingScheduler)
4. Progressive Interview Days 1-14 Going deeper + product feedback + discovery nudges UNVERIFIED — reported built March 26; re-audit required (see §0)

Layers 1-3 are confirmed. Layer 4 reads from all three to decide WHAT to ask and WHEN.


3. QUESTION SOURCES — STRUCTURE

Total: 45 questions across four sources.

Source Count Type Mandatory?
A — Depth (onboarding-steered) 24 Goal-gated + Universal Yes
B — Feature feedback (usage-triggered) 14 1 per module Yes
C — Discovery nudges (non-usage) Dynamic (template) Goal × unvisited module "Not now" allowed on nudge tour; follow-up profiling Q is mandatory
D — Experience check-ins (fixed-day) 7 Days 3/5/7/10/12/13/14 Yes — UNVERIFIED whether scheduler fires (see §0)

Note on Source A count: original v2.2 spec estimated ~25; Gamma's March 26 build expanded to 24 concrete questions (3 universal + 21 goal-specific across 8 goals). Total across all sources remains 45.


4. QUESTION BANK — FULL VERBATIM

Source A — Depth Questions (Onboarding-Steered, 24 total)

Asked only if the user selected the matching goal in onboarding Step 6. Read user_goals_list from SharedPreferences.

Health Goal (5 questions) — feeds traits: health_relationship, life_stage

  • A-H1 — "Specifically what in health? Sleep, nutrition, fitness, or mental health?" (multi-select)
  • A-H2 — "How would you rate your sleep quality?" (Great / OK / Struggling)
  • A-H3 — "Exercise frequency?" (Daily / Few times a week / Rarely / Want to start)
  • A-H4 — "Nutrition awareness?" (Track everything / I try / Eat what's available)
  • A-H5 — "Any specific health goals?" (open text, optional — only Source A question with optional text)

Money Goal (3 questions) — feeds trait: financial_attitude

  • A-M1 — "Financial comfort?" (Comfortable / Careful / Struggling / Rather not say)
  • A-M2 — "Biggest financial challenge?" (Budget / Unexpected expenses / Saving / Debt)
  • A-M3 — "Do you track expenses?" (Religiously / Sometimes / No, I should)

Productivity Goal (3 questions) — feeds traits: work_rhythm, planning_style

  • A-P1 — "Morning or night person?" (Early bird / Night owl / Depends)
  • A-P2 — "How do you manage tasks?" (Lists / Calendar / Mental notes / Chaos)
  • A-P3 — "Biggest productivity blocker?" (Meetings / Distractions / Unclear priorities / Energy crashes)

Family Goal (2 questions) — feeds traits: life_stage, social_orbit

  • A-F1 — "Household size?" (Just me / Partner / Family with kids / Roommates / Multi-gen)
  • A-F2 — "Who do you coordinate with most?" (Partner / Kids / Coworkers / Friends / Parents)

Fitness Goal (2 questions) — feeds trait: sports_relationship

  • A-FT1 — "Current routine?" (Daily / Few times a week / Sporadic / Starting fresh)
  • A-FT2 — "Training preference?" (Gym / Home / Outdoor / Mix)

Learning Goal (2 questions) — feeds trait: learning_style

  • A-L1 — "Building skills in?" (multi-select, open)
  • A-L2 — "Short bursts (25 min) or deep sessions (50+ min)?"

Career Goal (3 questions) — feeds traits: work_rhythm, life_stage, aesthetic_preference (board vs list)

  • A-C1 — "Work status?" (Employed / Self-employed / Student / Stay-at-home / Retired)
  • A-C2 — "Solo or team?" (Solo / Small team / Large org)
  • A-C3 — "Board view or list view for projects?"

Creativity Goal (2 questions) — feeds trait: creative_rhythm

  • A-CR1 — "Daily prompts or freeform?"
  • A-CR2 — "When does inspiration hit?" (Morning / Late night / Random / During exercise)

Universal (not goal-gated, everyone gets these — 3 questions) — feeds traits: communication_style, tech_comfort, mobility_pattern

  • A-U1 — "Communication preference?" (Quick texts / Calls / In person / Email)
  • A-U2 — "Technology comfort?" (Love trying new / Use what works / Keep it simple)
  • A-U3 — "Commute?" (Drive / Public transit / Walk-bike / Remote)

Source B — Feature Feedback (Usage-Triggered, 14 total)

Asked after first meaningful use of each module. Tracked via feature_first_use_{module} + feature_feedback_asked_{module}.

  • B-1 — Money — "How was setting up your first budget?"
  • B-2 — Events — "Week starts Sunday or Monday?"
  • B-3 — Streams — "Was writing that note easy? Anything missing?"
  • B-4 — Projects — "How did creating that project feel?"
  • B-5 — People — "Contacts imported smoothly?"
  • B-6 — Focus — "How was that focus session? Too short, right, too long?"
  • B-7 — Wellbeing — "Health tracking — useful or overwhelming?"
  • B-8 — Sessions — "How was that session/recipe?"
  • B-9 — Sports — "Found your teams? Missing any leagues?"
  • B-10 — Reader — "Reading experience comfortable? Font size OK?"
  • B-11 — Travel — "Trip setup smooth? Anything missing for your destination?"
  • B-12 — Planning — "Year wizard useful or too structured?"
  • B-13 — Marketplace — "How was that capsule? Useful, basic, or advanced?"
  • B-14 — Insights — "Dashboard making sense? What would you add?"

Timing matrix (research-backed):

Feature Type Trigger Rationale
Micro-Action (quick add task, log meal) Immediate (8-15 s delay) Low cognitive load, UI friction memory is acute
Setup & Configuration (link bank, create project) Session end or next launch Complex tasks need focus
Sustained Habit (3-day focus streak, week of budget) Next day Morning Pulse Measures psychological satisfaction
Reflective Analysis (viewing weekly insights) Same evening Wind Down User needs time to process

Source C — Discovery Nudges (Non-Usage, Dynamic)

Not a fixed bank — generated from user_goals_list × non-visited modules. Template:

"I noticed you're interested in {goal} but haven't explored {module} yet. Want me to show you what it can do?"

Follow-up (mandatory, fires 48 h after decline): "No pressure! What's been keeping you from trying it — too busy, not sure where to start, or not interested right now?"

Caps: - Global: max 1 discovery nudge per 48 h - Per-module: max 2 lifetime nudges; then that module's nudges are suppressed permanently - Nudge tour itself: "Not now" allowed (it's an offer, not profiling). The follow-up profiling Q is MANDATORY.

Source D — Experience Check-ins (Fixed-Day, 7 total) — UNVERIFIED

Fires on specific trial days regardless of usage. Per §0, whether the scheduler is firing these is UNVERIFIED for v2.7.

  • D-1 (Day 3) — "How's your first few days?" (emoji scale 1-5)
  • D-2 (Day 5) — "What do you use alaivOS for most?" (multi-select)
  • D-3 (Day 7) — "If you could change one thing, what?" (open text)
  • D-4 (Day 10) — "Found a mode that fits?" (list of active modes + "none yet")
  • D-5 (Day 12) — "Privacy: essential, important, or not top of mind?" — feeds trait privacy_posture
  • D-6 (Day 13) — "Two weeks in — how's it going?" (emoji scale 1-5)
  • D-7 (Day 14) — "One thing you can't live without?" (open text)

5. THE 11 TRAITS (Composite Profile)

The composite trait profile is the unit that determines Elite unlock (§6). A trait is "populated" when at least one question tagged to that trait has been answered (or inferred from passive profiling Layer 3).

# Trait Primary feeding questions Secondary signals
1 Life Stage A-F1, A-F2, A-C1 Onboarding age/sex, family-module usage
2 Financial Attitude A-M1, A-M2, A-M3 Money module usage cadence
3 Health Relationship A-H1, A-H2, A-H3, A-H4, A-H5 Wellbeing module, sleep logs
4 Sports Relationship A-FT1, A-FT2 Sports module leagues, attendance
5 Learning Style A-L1, A-L2 Reader/capsule usage, session lengths
6 Work Rhythm A-P1, A-P3, A-C2 Focus-session duration, event patterns
7 Planning Style A-P2, A-C3, B-12, D-4 Projects vs streams usage ratio
8 Communication Style A-U1, A-F2 Call vs message frequency, VIP list
9 Tech Comfort A-U2 Capsule installs, advanced-settings usage
10 Aesthetic Preference A-C3 Theme choice, wallpaper, glass density
11 Privacy Posture D-5 Ghost opt-in, Checkup opt-in, share-location toggles

Trait IDs correspond to trait_{key} entries in SharedPreferences and to columns in the ai_personas row derived at trial end.

Additional secondary traits referenced in the older spec (social_orbit, creative_rhythm, mobility_pattern) are rolled up into the 11 above for the purpose of the Elite unlock threshold.


6. ELITE UNLOCK — TWO GATES (OR)

Elite features (adaptive scheduling, AI health insights, deep cross-module correlations) require enough trait coverage for PromptAssembler Layer 1 to produce a meaningfully personalized persona. The unlock is capability-driven, not transactional.

Required (must be populated): - Life Stage - Financial Attitude - Health Relationship - Plus at least 3 of the remaining 8

Minimum: 6 of 11 traits populated.

Elite unlocks when EITHER: 1. Trait Completeness Threshold is met (6+ categories), OR 2. Day 14 is reached (deterministic fallback — auto-complete with whatever data exists)

Day 12 soft push: if below threshold, Laiv elevates remaining questions with value framing: "Elite unlocks in 2 days, and I'm almost ready to configure your advanced features. A few more preferences will make a big difference."

Day 14 batch: any remaining gaps are grouped into a brief completion flow (max 5 questions). Still mandatory, but efficient: "I have a few last questions to finish setting up your Elite experience."

Fallback: if the user deflects every question (3 attempts each), Day 14 auto-completes with defaults. Poor profile = generic Elite. Rich profile = deeply personalized Elite. Every user reaches Elite — the trait data just improves quality.

On unlock: markQuestionnaireCompleted() → AppTier transitions proTrial → eliteTrial.

This is the anti-abuse spine (ANTI_ABUSE_SPEC.md §3). Combined with Day 14 mandatory phone verification, the interview prevents "skip interview → free Elite without commitment" abuse.


7. DELIVERY ENGINE

7.1 Service: ProgressiveInterviewService

File: lib/core/services/progressive_interview_service.dart — UNVERIFIED presence (§0).

Responsibilities: - Build question queue (prioritized by source + timing) - Track answered / pending / declined in SharedPreferences - Read onboarding goals to filter Source A - Read DimensionSignalCollector for Source B / C triggers - Fire Source D on scheduled days - Enforce: max 2 Qs/day, mandatory (no skip on A/B/D), 3-attempt deflection

7.2 Queue Priority

Each day, the engine selects up to 2 questions in this order:

  1. Overdue re-asks (deflected Qs on attempt 2 or 3) — highest
  2. Feature feedback (usage-triggered, time-sensitive)
  3. Experience check-ins (fixed-day, must fire on scheduled day)
  4. Depth questions (onboarding-steered) — fill remaining slot
  5. Discovery nudges (non-usage) — lowest; only if nothing else

7.3 Timing Windows — Natural Moments Only

Moment When How
Morning Pulse First app open after 6 AM Card in Morning Pulse feed (prism_insight_card.dart)
Evening Wind Down App open after 7 PM (Wind Down mode active) Card inside Wind Down flow (evening_wind_down_card.dart)
Post-Task After completing a task, logging a meal, finishing a focus session Slide-in after completion animation
Module Entry First visit to a module each day Subtle banner (discovery nudges only)

Never during: active focus sessions, mid-data-entry, timer running, navigation in progress.

7.4 Question UI — Glass Card from Laiv

Not a form. Not a modal. A glass card inline with Laiv chat.

+-------------------------------------+
|  Laiv                               |
|                                     |
|  "You set up your first budget      |
|   yesterday - how's it feeling?"    |
|                                     |
|   [Great] [Confusing] [Meh]         |
|                                     |
|   (no skip on A / B / D)            |
+-------------------------------------+
  • Glass UI mandate: ClipRRect → BackdropFilter(blur:24) → Container(gradient white 0.14→0.05, border white 0.2)
  • Colors: withValues(alpha: X) only
  • Font sizes: Responsive.sp()
  • 5 input types: text, single choice, multi choice, slider, yes/no
  • Slide + fade animation, haptic feedback
  • ARB keys (21 locales): interviewTypeAnswer, commonYes, commonNo, commonNotNow, commonDone

7.5 Deflection Handling

When a mandatory question appears and the user doesn't interact:

  1. Attempt 1 — surfaced at next natural moment
  2. Attempt 2 — re-asked at next natural moment, 1+ day later
  3. Attempt 3 — re-asked once more; if no response, mark declined, move on
  4. Never block the app, show a wall modal, or prevent navigation

7.6 Ground Truth #11 Compliance

Requirement Implementation
Mandatory No skip button on A / B / D. Only Source C nudge tours accept "Not now."
No cancel Card cannot be dismissed. Stays until answered or app closes.
No gesture dismiss No swipe-to-dismiss on interview cards.
Re-ask if ignored Max 3 attempts, spaced across natural moments.
Completes by Day 14 Day 13-14 batch push covers remaining Qs.
Every user gets Elite Completion (or Day 14) triggers markQuestionnaireCompleted()eliteTrial.
21 days guaranteed 14 Pro + 7 Elite — interview guarantees the Elite unlock.

8. DATA FLOW & STORAGE

Onboarding (Day 0)
  -> SharedPreferences: user_goals_list, user_roadblock, user_management_style
  -> Supabase user_profiles: 6 fields persisted for reinstall recovery (v2.7)
  -> ProgressiveInterviewService reads these to steer Source A

Progressive Interview (Days 1-14)
  -> SharedPreferences: interview_q_{id}_answer, _asked_at, _attempts, _status
  -> SharedPreferences: trait_{key} (11 keys, populated as answers arrive)
  -> DimensionalEngine: dimension signals for answered questions
  -> Analytics: interview_started, interview_question_answered,
                interview_question_declined, interview_nudge_accepted/declined,
                interview_completed, interview_completion_day
  -> Product Feedback DB: open-text answers (D-3, D-7, A-H5, A-L1) for J review

Passive Profiling (parallel, Days 1+)
  -> DimensionSignalCollector: module usage -> trait inference
  -> ProfilingScheduler: cluster evaluation (daily -> every 3 days)
  -> ProgressiveInterviewService reads usage to trigger B + C

Elite Unlock (6+ traits OR Day 14)
  -> markQuestionnaireCompleted()
  -> AppTier: proTrial -> eliteTrial
  -> Derive ai_personas row from trait_{key} set + onboarding + passive signals
  -> PromptAssembler Layer 1 reads ai_personas on every Laiv inference
  -> Elite features unlock; interview_completed analytics

8.1 ai_personas Row (Persona for PromptAssembler Layer 1)

Derived at interview completion. Feeds Layer 1 persona injection on every Laiv inference (on-device and Ghost). Schema sketch:

Column Source
user_id account
persona_preset PersonalitySettings choice (Coach/Friend/Assistant/Mentor/Custom)
persona_sliders 4-slider JSON
life_stage trait
financial_attitude trait
health_relationship trait
sports_relationship trait
learning_style trait
work_rhythm trait
planning_style trait
communication_style trait
tech_comfort trait
aesthetic_preference trait
privacy_posture trait
open_text_snippets A-H5, A-L1, D-3, D-7 (optional, may be null)
goals_list onboarding
roadblock onboarding
updated_at timestamp

PromptAssembler Layer 1 reads this row and constructs the persona prefix the model sees on every turn. See VOICE_AND_AI.md §PromptAssembler.

8.2 SharedPreferences Keys

  • interview_started_at — timestamp
  • interview_completed_at — timestamp (null until done)
  • interview_q_{id}_answer
  • interview_q_{id}_asked_at
  • interview_q_{id}_attempts (0-3)
  • interview_q_{id}_status — answered / pending / declined
  • interview_daily_count_{date} — max 2
  • trait_{key} — 11 keys, populated as answers arrive
  • feature_first_use_{module} / feature_feedback_asked_{module}

9. ESTIMATED QUESTIONS PER USER

Scenario A B C D Total
Active user (3 goals, 8 modules) ~12 ~8 ~0 7 ~27
Moderate user (2 goals, 4 modules) ~9 ~4 ~2 7 ~22
Passive user (1 goal, 2 modules) ~5 ~2 ~4 7 ~18
Minimum (deflects everything, 3 attempts) 3 0 0 7 ~10

Max 2 Qs/day × 14 days = 28 slots. Even the most active user fits comfortably.


10. DEAD CODE — DO NOT REUSE

Per v2.7 TRIAL audit, these are orphaned and must remain @Deprecated. Do not wire new features to them.

Old artifact Status Replacement
trial_questionnaire_screen.dart (G-3, 7-screen modal, Day 14 wall) DEAD CODE Progressive interview (this spec)
interview_screen.dart (27-question orphan) DEAD CODE Progressive interview (this spec)
Original onboarding_screen.dart DEAD CODE NewOnboardingScreen
"Up to 21 days" conditional-Elite language OBSOLETE "21 days guaranteed" — interview is mandatory
"25 questions across Days 1-14" OBSOLETE COUNT 45 questions (24 A + 14 B + dynamic C + 7 D)
Per-skill Ghost pricing / capability gating DEAD (GT violates) Credits-only gate

11. IMPLEMENTATION SCOPE (Reported — UNVERIFIED)

Per Addendum (March 26, 2026, Omega v2.3), Gamma reported:

Files created: - lib/core/models/interview_question.dart (88 lines) - lib/core/services/progressive_interview_questions.dart → built as interview_question_bank.dart (277 lines) - lib/core/services/progressive_interview_service.dart (282 lines) - lib/core/components/interview_card.dart (342 lines) - test/services/progressive_interview_test.dart (31 tests passing at build time)

Files modified: - prism_insight_card.dart — interview section after Morning Briefing - evening_wind_down_card.dart — interview section inside card body - dashboard_screen.dart — auto-init via FutureProvider - providers.dartprogressiveInterviewServiceProvider - subscription_service.dart — wire completion check

All of the above must be re-verified per §0 before launch.


12. WHAT THIS SPEC DOES NOT COVER (future sprints)

  • Contact import → VIP → Family Group flow — referenced in TRIAL_AND_ONBOARDING.md §2.3, separate sprint
  • Day 0-28 experience orchestration — Ghost trial moment Days 5-7, conversion cadence, referral prompts
  • Shareable savings card — triggered by SaaS-Tax question, card generator not built
  • Referral tracking ↔ interview completion wiring — separate sprint
  • Checkup integration — Day 0 / Day 14 / Day 28 Checkups are covered in TRIAL_AND_ONBOARDING.md and VOICE_AND_AI.md, not here; but Checkup results enrich the same ai_personas row post-trial

13. SUMMARY

  • 45 questions total: 24 Source A + 14 Source B + dynamic Source C + 7 Source D
  • Mandatory — GT #11; no skip on profiling questions; "Not now" only on Source C nudge tours
  • 11 composite traits — Elite unlocks at 6/11 populated OR Day 14 deterministic fallback, whichever first
  • Delivery: Laiv glass card at natural moments (Morning Pulse / Evening Wind Down / post-task); never a standalone modal
  • Storage: SharedPreferences (per-question + trait keys) → ai_personas row → PromptAssembler Layer 1
  • DEAD CODE: old G-3 7-screen questionnaire, old 27-question interview_screen.dart, "up to 21 days" language
  • UNVERIFIED for v2.7: Layer 4 engine presence and wiring — Delta must re-audit before launch (§0)