kalei/docs/codex phase documents/phase-2-core-experience-build.md

Phase 2 - Core Experience Build

Duration: 3-5 weeks Primary owner: Mobile + backend in parallel

1. Objective

Ship Kalei's core user experience end-to-end:

• Mirror with fragment highlighting and inline reframe
• Turn generation with 3 perspectives and micro-action
• Lens goals, daily actions, and daily focus/affirmation flow
• Gallery/history views for user continuity

2. Entry Criteria

Phase 1 exit checklist complete.

3. Product Scope In This Phase

3.1 Mirror (Awareness)

Required behavior:

• user starts mirror session
• user submits messages
• backend runs safety precheck first
• backend runs fragment detection on safe content
• app highlights detected fragments above confidence threshold
• user taps fragment for inline reframe
• user closes session and receives reflection summary

Backend work:

• finalize mirror_sessions, mirror_messages, mirror_fragments
• add close-session reflection endpoint
• add mirror session list/detail endpoints

Mobile work:

• mirror compose UI
• highlight rendering for detected fragment ranges
• tap-to-reframe interaction card
• session close and reflection display

3.2 Turn (Kaleidoscope)

Required behavior:

• user submits a fragment or thought
• backend runs safety precheck
• backend generates 3 reframed perspectives
• backend returns micro-action (if-then)
• user can save turn to gallery

Backend work:

• finalize turns table and categories
• add save/unsave state
• add history list endpoint

Mobile work:

• turn input and loading animation
• display 3 patterns + micro-action
• save to gallery and view history

3.3 Lens (Direction)

Required behavior:

• user creates one or more goals
• app generates or stores daily action suggestions
• user can mark actions complete
• optional daily affirmation/focus shown

Backend work:

• finalize lens_goals, lens_actions
• daily action generation endpoint
• daily affirmation endpoint through AI gateway

Mobile work:

• goal creation UI
• daily action checklist UI
• completion updates and streak indicator

4. Deep Technical Workstreams

4.1 Prompt and Output Contracts

Create strict prompt templates and JSON output contracts per feature:

• Mirror fragment detection
• Mirror inline reframe
• Turn multi-pattern output
• Lens daily focus output

Require server-side validation of AI output shape before returning to clients.

4.2 Safety Integration

At this phase safety must be complete for user-facing flows:

• all Mirror and Turn requests pass safety gate
• crisis response path returns resource payload, not reframe payload
• safety events are queryable for audit

4.3 Entitlement Enforcement

Enforce in API middleware:

• free turn daily limits
• free mirror weekly limits
• spectrum endpoint lock for non-entitled users

Add clear response codes and client UI handling for plan limits.

4.4 Performance Targets

Set targets now and test against them:

• Mirror fragment detection p95 under 3.5s
• Turn generation p95 under 3.5s
• client screen transitions under 300ms for cached navigation

5. Detailed Build Plan

Week 1:

• finish Mirror backend and basic mobile UI
• complete fragment highlight rendering

Week 2:

• finish inline reframe flow and session reflections
• add Mirror history and session detail view

Week 3:

• finish Turn backend and mobile flow
• add save/history integration

Week 4:

• finish Lens goals and daily actions
• add daily focus/affirmation flow

Week 5 (optional hardening week):

• optimize latency
• improve retry and offline handling
• run end-to-end QA pass

6. Test Plan

Unit tests:

• prompt builder functions
• AI output validators
• entitlement middleware
• safety decision functions

Integration tests:

• full Mirror message lifecycle
• full Turn generation lifecycle
• Lens action completion lifecycle

Manual QA matrix:

• normal usage
• plan-limit blocked usage
• low-connectivity behavior
• crisis-language safety behavior

7. Deliverables

Functional deliverables:

• Mirror v1 complete
• Turn v1 complete
• Lens v1 complete
• Gallery/history v1 complete

Engineering deliverables:

• stable endpoint contracts
• documented prompt versions
• meaningful test coverage for critical flows
• feature-level latency and error metrics

8. Exit Criteria

You can exit Phase 2 when:

• users can complete Mirror -> Turn -> Lens flow end-to-end
• plan limits and safety behavior are consistent and test-backed
• no critical P0 bugs in core user paths
• telemetry confirms baseline latency and reliability targets

9. Risks To Watch

• Risk: output variability from model causes UI breakage.
  • Mitigation: strict response schema validation and fallback copy.
• Risk: too much feature scope in one pass.
  • Mitigation: ship v1 flows first, defer advanced UX polish.
• Risk: latency drift from complex prompts.
  • Mitigation: simplify prompts and use cached static context.