Routines — requirements

Epic. MVP-1 requirements breakdown for the Routines ⭐ differentiator (see the feature architecture). A Routine is an ordered sequence of chores rendered on the Today surface as a first-then scaffold — the primary executive-function support mechanism in Rewhaven. This feature requires a new SDK sequence model before UI work can begin.

Type	Functional ⭐
Layer (build approach)	Cross — SDK sequence model + Today UI
RICE	R 7 × I 3 × C 80% / E 4 = 4.2 · Tier MVP-1
KPI (summary)	Routine completion rate — see Success criteria
Traces to	feature routines · C4 components
Depends on	Today · Money

Success criteria (definitive KPI)

Success = ≥ 40% of activated households have created ≥ 1 routine, AND ≥ 65% routine completion rate (sequences fully finished / sequences started), sustained across weeks 2–4 after activation.

• Adoption metric: proportion of activated households that create and activate ≥ 1 routine.
• Adoption target: ≥ 40% — routines are opt-in; the bar reflects meaningful uptake, not universal use.
• Completion metric: routine_completed events / routine_started events, per household per week.
• Completion target: ≥ 65% — a sequence finishing at 65%+ reads as a reliable habit scaffold, not a novelty.
• Window: sustained across weeks 2–4 post-activation (activation = household's first approved chore completion).
• Why these bars: low adoption signals the builder is too hard or undiscoverable; low completion signals sequences are too long, wrong time-of-day, or poorly ordered — each failure mode has a different remediation path.
• Guardrail (token-fade): routine completion rate must hold or improve as the token economy fades across weeks 5–8. A rate that drops when tokens drop indicates the sequence was extrinsically reinforced only — that is a regression against the intrinsic-motivation thesis.
• Baseline: no install base yet — treat 40% / 65% as the launch hypothesis, re-baseline from the first wk-2 cohort.

Analytics — events to record

All member references are opaque/hashed; no step content, no chore names, no minor PII (see COPPA). Emitted through the consent-gated analytics substrate. Internal-BI only — never marketing.

Event	When	Key properties	Feeds
routine_created	Admin saves a new routine	stepCount, hasSchedule	builder adoption
routine_started	Member opens the first-then strip for step 1	routineId (opaque), stepCount	completion denominator
routine_step_completed	A step within a running routine is completed	routineId (opaque), stepIndex, totalSteps	step-funnel drop-off analysis
routine_completed	All steps in a routine are completed in one session	routineId (opaque), stepCount, hadCompletionBonus	primary KPI → completion rate

Both routine_started (denominator) and routine_completed (numerator) must ship with the feature — the completion-rate KPI is unmeasurable otherwise. stepIndex in routine_step_completed enables drop-off analysis (which step breaks the sequence) without logging any content.

Scope

Routines deliver a first-then executive-function scaffold on the Today surface: an admin-authored ordered sequence of chores that a member works through step-by-step. MVP-1 covers the routine builder (admin), the first-then run UI (member, on Today), partial- session persistence, and daily or day-of-week scheduling. Member reordering, multi-day spanning sequences, and bonus rewards are not MVP-1.

Functional requirements

FR-ROUTINE-1 — Admin creates an ordered routine (sequence of chore references)

Priority: P1 · Status: ❌ not built Statement. As an admin, I can create a named routine by selecting existing chores in order, so members have a predictable first-then sequence to follow. Acceptance

• Given an admin is on the Routines builder When they pick chores, set a name, and assign members Then a Routine entity is persisted with orderedStepRefs and assignedMemberIds.
• Given a referenced chore is later deleted When the routine loads Then the step is marked inactive and the sequence skips it silently — no crash, updated stepCount emitted on next event.

FR-ROUTINE-2 — Routine renders on Today as a first-then strip

Priority: P1 · Status: ❌ not built Statement. As a member with an assigned routine, I see a first-then strip on Today above the individual chore list, showing the current step highlighted and completed steps behind me. Acceptance

• Given a routine assigned to me with 3 steps When Today loads Then the strip shows step 1 active, steps 2–3 as upcoming; routine_started fires on first step interaction.
• Given I have no routines assigned When Today loads Then no strip appears; the standard chore list is unaffected.
• Given the routine is not scheduled for today When Today loads Then the strip does not appear.

FR-ROUTINE-3 — Completing a step advances the sequence

Priority: P1 · Status: ❌ not built Statement. As a member, marking a step done within the first-then strip completes that chore through the normal approval path and advances the sequence to the next step. Acceptance

• Given step 1 is active When I mark it done Then chore_completed (or completion_submitted if gated) fires through the standard earn path; the strip advances to step 2 and emits routine_step_completed.
• Given I complete the final step Then the strip shows a completion state and emits routine_completed.
• Steps cannot be skipped in MVP-1; out-of-order completion is not supported.

FR-ROUTINE-4 — Partial routine state persists through the session boundary

Priority: P1 · Status: ❌ not built Statement. As a member, if I leave Today mid-sequence and return later the same day, my progress is preserved so I can resume without losing context. Acceptance

• Given I complete steps 1–2 of 4 and close Today When I reopen Today the same calendar day Then the strip shows steps 1–2 done and step 3 active.
• Given a new calendar day starts When Today reloads Then the RoutineRun resets; chores that already earned tokens follow the standard rollover policy (FR-TODAY-9).

FR-ROUTINE-5 — Routine schedule (daily or day-of-week)

Priority: P2 · Status: ❌ not built Statement. As an admin, I can set a routine to appear daily or on selected days of the week, so the strip only shows when scheduled. Acceptance

• Given a routine scheduled for Mon/Wed/Fri When Today loads on Tuesday Then the strip does not appear for assigned members.
• Given a routine set to every day When Today loads on any day Then the strip appears for all assigned members.

Architecture considerations

• New SDK sequence model — Routine (id, householdId, name, orderedStepRefs, assignedMemberIds, schedule) and RoutineRun (routineId, date, completedStepIndices) are new first-class entities in client_sdk. RoutineService enforces step order and inactive-step skipping; RoutineAdapter handles Drift + Supabase persistence. This must be built before any UI work.
• One data path — TodayBloc extended (or a sibling RoutineBloc) → RoutineRepository → client_sdk facade → RoutineService → adapter. No direct Drift/Supabase access in presentation; no exceptions.
• Ordering — orderedStepRefs is the admin-set source of truth in MVP-1; members cannot reorder. The service derives the active step index from completedStepIndices.
• Composes with Today — the first-then strip renders above the flat chore list on Today and shares the chore_completed / completion_submitted earn path so tokens credit correctly and approval gates are respected. No duplicate earn logic.
• Offline-first — RoutineRun step completions queue offline identically to chore_completed; the strip must be readable and advanceable without network access. Drift is the write-through cache; routine_completed must survive an offline→online transition without double-counting.
• Household-scoped RLS — routines and routine_runs rows carry household_id; the cloud adapter relies on household-scoped policies consistent with SP3. No cross-household routine access.

Design work (ahead of build)

All routine UI is net-new — no design exists yet. Required before build begins:

• Routine builder (admin): chore picker with order control, routine name field, member assignee picker, schedule selector (daily / day-of-week toggles).
• First-then run UI on Today: the strip itself — step indicator (dots or 1-of-N label), current-step highlight, completed-step treatment (checked / faded), completion celebration state.
• Progress within a sequence: visual treatment for partial completion showing what remains.
• Confirm whether the empty / no-routine state on Today needs a placeholder or strips silently.

Decisions (resolved for MVP-1)

Resolved — see the MVP-1 decisions log for the canonical record, rationale, and status legend (✅ decided · ⚖️ counsel confirms · 🔜 MVP-1.x).

• D-ROUTINE-1 — Skip a step (FR-ROUTINE-3). ✅ Strict order enforced in MVP-1 (no skip) — matches the scaffolding intent for the core audience; a skip affordance is deferred pending research.
• D-ROUTINE-2 — Cross-day rollover (FR-ROUTINE-4). ✅ Co-resolved with FR-TODAY-9: an incomplete routine/chore rolls to "overdue today" (carried, not reset) — one shared rule across Today and Routines.
• D-ROUTINE-3 — Completion bonus. ✅ An optional discrete completion bonus, admin-configurable per routine (default off) — RoutineService earn path + hadCompletionBonus analytics prop.
• D-ROUTINE-4 — RoutineRun key. ✅ Composite (routineId, date) — natural daily idempotency, aligns with the rollover model; deferred multi-day routines extend with a span rather than breaking the key.

Out of scope (MVP-1)

• Member reordering of routine steps → admin-only in MVP-1.
• Multi-day routines (sequence spans more than one session day) → deferred; RoutineRun date-key must not preclude it.
• Completion bonus token award → open decision; deferred pending resolution above.
• Visual timer integration within the first-then strip → MVP-2.
• AI-suggested routine templates → recommender sub-project.
• Standalone routine surface outside Today → Today is the sole execution surface in MVP-1.