Phase 3 — Learnings from Previous Explorations

Phase 3 -- Learnings from Previous Attempt

Version: 1.0 Date: February 25, 2026 Input: Architecture Proposals (A, B, C) + Design Review of Exploration A Mockup + Phase 1 Problem Brief + Phase 2 Design Principles Organizing Principle: Weekly Rhythm -- "The app follows my weekly learning cycle."

Preamble

This document extracts concrete lessons from the first attempt at implementing Proposal A as a mockup. The mockup reached approximately 80% alignment with the specification and 57% coverage of the full User Capability Map. That is a useful signal: it tells us what the Proposal A spec got right (the mockup could follow it), what the spec left ambiguous (the mockup had to improvise), and what the spec missed entirely (the mockup did not attempt it). Phase 4 must resolve every gap identified here.

What Worked in Proposal A (Preserve These)

1. The Schedule Page -- Near-Perfect Execution (95% alignment)

The Schedule page is the strongest screen in the mockup and the strongest section of the Proposal A spec. It implements: timezone selector with multiple options (EST, GMT, GST, AEDT), timezone display in the header, week navigator with arrows, calendar day strip, session type filters (All / Classes / QRCs), session cards with type badges and descriptions, Join Zoom buttons, Add to Calendar buttons, RSVP toggles with attendee counts, session detail modals, and deadline cards showing submission cutoffs. The design review found zero missing elements.

Why it worked: The spec was precise. It described the exact components, their states, and their relationships. It left nothing for the implementer to guess. The Schedule page also maps to a well-understood pattern (calendar views) that has clear iOS conventions.

Preserve: The full Schedule page design. Carry it forward as-is into Phase 4. It solves the P0 timezone issue, eliminates the 5-click-deep Google Calendar link, and passes every quality bar test from Phase 2 (C4: Timezone Always Displayed, S3: Core Task Reach, S4: Hidden Features Eliminated for schedule).

2. The Submit Page -- Excellent Submission UX (95% alignment)

The Submit page implements the core recording workflow correctly: week indicator, attempts counter ("1 of 2 Attempts Remaining"), Quranic text display in Amiri font with RTL rendering, tap-to-record with visual feedback, playback before submit, re-record option, confirmation dialog with explicit warning, success state with animation, submission history showing prior weeks, "Feedback Ready" badge, feedback bottom sheet with audio playback, and follow-up question input.

Why it worked: The submission flow is the most linear workflow in the app -- record, review, submit. Linear flows are easiest to spec and implement. The spec addressed the P0 issues directly (confirmation dialog for accidental submissions, proper Quranic font, submission history).

Preserve: The recording interface, confirmation dialog, feedback sheet pattern, and submission history list. These solve P0 issues (missing submission history, non-standard font, accidental submissions) and pass quality bar tests (C5: Standard Quranic Font on First Encounter, N3: First Submission Without Help).

3. The Learn Page -- Unified Week View (90% alignment)

The Learn page implements the key Proposal A insight: organizing content by week rather than by feature type. It uses expandable week cards that contain lesson videos (with checkboxes and duration), learning objectives, a submission sub-tab, and a "Feedback Ready" badge. The segmented control ([Current Week] [All Weeks]) enables progressive disclosure -- current week expanded, past weeks collapsed.

Why it worked: Grouping by week is the architectural decision most aligned with the Weekly Rhythm principle. The Phase 2 design principles (Content Principle 2: Grouping by Time and Progress) demand that "items belonging to the same week must be co-located." The Learn page does this.

Preserve: The week-as-unit grouping pattern, expandable week cards, the co-location of lesson + submission + feedback within a single week entry, and the segmented control for temporal filtering. This directly satisfies quality bar test C3 (Week-Grouped History).

4. The More Page -- Coach and Profile Surfacing (90% alignment)

The More page surfaces previously hidden features: profile card with avatar, name, level, and semester; stats display; My Quran Coach section with photo, name, message button, and bio; account management (Personal Details, Subscription, Notifications); Help Center; App Settings; and Sign Out. The coach section is prominent, not buried.

Why it worked: The More page is a standard iOS pattern (Settings/Profile hub) and the spec was clear about what belongs here. Moving the Quran Coach from the hamburger menu to a prominent section with a message action solves the discoverability problem identified in Phase 1.

Preserve: The coach section design, the profile card, and the overall More page organization. These satisfy quality bar tests S4 (Hidden Features Eliminated for coach identity and support) and L4 (Recovery Test -- support reachable in 2 taps).

5. The P0 Resolution Pattern

Six of seven P0 issues were addressed in the mockup. This validates that the Proposal A architecture creates natural homes for the fixes:

Preserve: The principle that every P0 fix must have a visible, discoverable home in the primary tab structure -- not buried in settings or secondary screens.

What Didn't Work (Fix These)

1. The Today Page Failed the 3 Questions Test (60% alignment)

This is the single most important failure. The Today page is the home screen -- the first thing a student sees on every launch. Phase 2's quality bar test S1 requires that a person who has never used QuranFlow can answer "What week of the semester is this?" and "What should you do next?" within 10 seconds, without scrolling. The mockup's Today page fails this test.

Specific failures:

Why it matters: The Today page IS the Weekly Rhythm. If the home screen does not foreground the week, the organizing principle is not implemented. Phase 2's Principle Priority Stack puts "Temporal orientation first" above all other concerns. A Today page that shows a date instead of a week number has inverted the priority.

Fix required: The Today page must be completely redesigned with the week header as the dominant visual element, the level below it, a progress bar, a countdown, and status cards for lesson, submission, and upcoming sessions -- all without scrolling.

2. Tab Structure Deviates from Proposal A

The mockup uses: Today | Learn | Submit | Schedule | More. Proposal A specifies: Today | Learn | Schedule | Progress | More.

Two deviations:

Why it matters: The tab bar is the skeleton of the information architecture. Phase 2's Tab Worthiness Criteria state that a tab must be "a place, not an action" and must "represent a coherent, self-contained information space." Submit-as-a-tab is debatable: it is arguably an action (recording) dressed as a destination. Progress-as-a-tab is clearly a destination (the student's full history). This is a structural decision that Phase 4 must resolve definitively.

3. Pre-Semester Phase Is Completely Absent (12% coverage)

The mockup implements 1 of 8 pre-semester capabilities. Missing entirely:

Why it matters: Phase 2's quality bar test L1 (Pre-Semester State) requires that a student who has completed assessment but whose semester has not started sees: their assigned level, their Quran Coach's name, the number of days until semester start, and at least one action they can take now. The mockup cannot pass this test. Onboarding is where the app either hooks or loses the student. Phase 1 identifies that students who skip onboarding emails arrive to an app that "gives them no sense of place, no sense of time, and no sense of sequence -- and some give up within the first two weeks." The in-app onboarding must compensate for this.

4. No "Behind" State Handling

The mockup shows a student at Week 8 with normal progress. It does not address what happens when a student is behind. Phase 2's quality bar test L2 (Behind Test) requires: visible deficit messaging ("You are 2 submissions behind"), a catch-up path reachable in one tap, and neutral (not shaming) language. Proposal A's own trade-off analysis flagged this as a risk: "Students significantly behind may feel shame seeing 'Week 8' when they're on Week 5."

Why it matters: A substantial portion of students fall behind. The 12-of-15 completion requirement with 2-submissions-per-week catch-up policy means the app must actively support recovery. If the Today page only shows the current calendar week without acknowledging the student's actual position, it creates cognitive dissonance and potential shame. Phase 4 must design the behind state explicitly.

5. End-of-Course Assessment Phase Is Absent (0% coverage)

Zero implementation of Section 4 capabilities: EOC assessment screen, final results display, graduation flow, Level 4-to-Year 2 transition. Phase 2's quality bar test L3 (EOC Phase State) requires a distinct EOC card on the Home screen when the student has completed 12+ submissions and is eligible.

6. Session Recordings Are Missing (0% coverage)

Section 3E of the capability map (Find recordings, Filter recordings, Watch recordings, Track watched recordings) is at 0%. The Phase 1 Hidden Features Table lists session recordings as hidden behind "hamburger menu > Recordings > filter by date." The mockup does not surface them. Proposal A places them in "Progress tab > Past Sessions section" and in "Schedule > Past weeks," but since the Progress tab was not implemented, recordings have no home.

7. Font Settings UI Not Implemented

The mockup defaults to Amiri font (solving the P0 for first encounter), but there is no Settings UI for changing the font after onboarding. The Phase 1 audit notes that the font selector is one of 8 hidden features that must become discoverable. Phase 2 test S4 requires all 8 to be accessible without prior knowledge.

Elements from Proposals B and C Worth Incorporating

From Proposal B (Dashboard Command Center)

1. The Three-Card Dashboard Layout

Proposal B's home screen uses three equal-weight status cards side by side: Lesson (with video count), Submission (with status), and Feedback (with new count). Each card has a clear state and a single action button. This is a more information-dense approach than Proposal A's stacked cards, but it solves a real problem: the returning student who wants to assess all three statuses simultaneously without scrolling.

How to incorporate: The Today page should borrow the triptych pattern -- three status indicators visible in the top half of the screen -- but use it within Proposal A's temporal framework. The week header remains dominant at the very top; below it, three compact status cards (Lesson, Submission, Feedback) give the at-a-glance status. Below those, the day's sessions. This merges Proposal B's density with Proposal A's temporal anchoring. It directly serves the Phase 2 Return Test (N4): a returning student can state their submission status within 5 seconds.

2. Dedicated Feedback Tab Concept (Pending + History)

Proposal B gives Feedback its own tab with two views: Pending (submissions awaiting feedback) and History (all past feedback in chronological order, no complex date filters). This is a simpler, more scannable alternative to the current proposal's "feedback lives inside each week in the Learn tab."

How to incorporate: If Phase 4 decides that Progress deserves a tab, the Progress tab should adopt the Pending + History structure from Proposal B. Pending submissions at the top, then a reverse-chronological feed of all feedback grouped by week. This solves the feedback archives problem (Phase 1 Hidden Feature) and passes quality bar test C3 (Week-Grouped History). The key insight from B is that feedback should be browsable as a timeline, not only accessible by drilling into individual weeks.

3. Live Tab Combining Schedule + Recordings

Proposal B's Live tab uses a toggle: Schedule | Recordings. This co-locates the two things that relate to synchronous sessions -- upcoming ones and recorded past ones. It is more discoverable than Proposal A's approach (recordings in Progress tab, separate from Schedule).

How to incorporate: The Schedule tab should include a secondary access point to session recordings -- either as a toggle or as a "Past Sessions" section below the current week's schedule. Students who come to the Schedule tab looking for a session they missed should find the recording in the same location, not in a different tab.

4. Profile Tab with Full Account Hub

Proposal B's Profile tab includes: photo, name, level, week; My Quran Coach with message action; Account (Personal Information, Subscription & Billing, Learning History); Settings (Quranic Font Style, Notifications, Display); and Support (Help Center, Contact Support, FAQ). This is more comprehensive than the mockup's More page, particularly the inclusion of Learning History and the explicit "Quranic Font Style" setting.

How to incorporate: The More/Profile tab should adopt this full structure. Learning History is important for multi-semester students. The font setting must be explicitly labeled and accessible. These are Phase 1 requirements (Hidden Features Table, P0 font issue).

From Proposal C (Guided Journey)

1. The "Your Next Step" Single-Task Focus

Proposal C's Now tab shows exactly one task with a hero card: "YOUR NEXT STEP: Watch Lesson Video -- Video 2 of 3: Practice Stretches -- 12 minutes -- [Watch Now]." Below it, a single "Up Next" preview. This extreme focus is too restrictive as the default architecture (it fails Phase 2's Return Test because returning students cannot see full status), but the underlying pattern -- a context-dependent primary CTA that changes based on the student's state -- is valuable.

How to incorporate: The Today page should have a context-dependent primary action that adapts to the student's state within the weekly cycle. The state machine from Proposal C is precise and should be adopted:

This state machine should drive the primary action on the Today page, but the other status cards remain visible so the student retains full context.

2. The Journey Visualization (Progress as a Map)

Proposal C's Progress tab shows a vertical journey map: Week 1 through Week 15, each with a status indicator (completed, in-progress, upcoming), the current position highlighted, and achievements below. This is a motivating, scannable visualization that answers "how far have I come" at a glance.

How to incorporate: The Progress tab (if it earns a tab slot) should include a journey map as its header element. The map provides the macro-level temporal orientation that complements the Today page's micro-level (this week) orientation. Week 1 through Week 15, the student's current position, completed weeks, and the EOC assessment at the end. Tapping any completed week should expand to show that week's lesson, submission, and feedback -- preserving the week-as-unit grouping. This visualization also provides a natural home for the EOC assessment (Week 15 becomes "EOC Assessment" at the end of the journey).

3. Guided Onboarding Sequence

Proposal C specifies a multi-step onboarding: Welcome > Font selection (required) > Meet your Quran Coach > See your journey map > Land on Week 1. This is the most thorough onboarding of the three proposals. Proposals A and B mention onboarding but are less prescriptive.

How to incorporate: Adopt Proposal C's onboarding structure but adapt it for the Weekly Rhythm context:

  1. Welcome to QuranFlow + level placement confirmation
  2. Font selection (required, not skippable -- solves P0)
  3. Meet your Quran Coach (name, photo, brief bio)
  4. Your semester overview (Week 1 of 15, start date, weekly rhythm explanation)
  5. Land on Today page with Week 1 context

This ensures Phase 2 test L1 (Pre-Semester State) can pass and addresses Phase 1's finding that students who skip emails are completely lost.

4. The "Connect" Concept for Human Touchpoints

Proposal C groups all human connection into a single tab: Quran Coach, upcoming sessions, community, and support. While "Connect" as a standalone tab is not justified under Phase 2's Tab Worthiness Criteria (it mixes multiple information spaces), the insight is valid: the student's relationship with their coach, with live sessions, and with support are all interpersonal. These should feel connected, even if they live in different tabs.

How to incorporate: The Quran Coach should appear in multiple places contextually -- on feedback screens (who gave this feedback), on submission screens (who will review this), on the Today page (as a presence, not just in the More tab). Support should be reachable from multiple entry points: the More tab, a help icon on complex screens, and within the onboarding flow. The "interpersonal" layer should be woven through the app rather than isolated in one tab.

Open Design Questions

Phase 4 must make definitive decisions on each of these. They cannot be deferred.

Q1: What earns a spot on the tab bar?

The mockup uses: Today | Learn | Submit | Schedule | More (5 tabs). Proposal A specifies: Today | Learn | Schedule | Progress | More (5 tabs).

The core tension: Submit and Progress both have legitimate claims to a tab slot, but Phase 2 caps the tab bar at 4-5. If submission is folded into Learn (as Proposal A intends), the Learn tab carries the heaviest load in the app -- lessons, videos, recording, submission, and per-week feedback. Is that too much for one tab? Conversely, if Submit keeps its own tab, where does Progress live? And does a standalone Submit tab violate the "place not action" criterion?

Phase 4 must commit to one tab bar and justify every slot against the Tab Worthiness Criteria from Phase 2.

Q2: What dominates the home screen above the fold?

The mockup leads with a date and a small "Current Week 8" badge. Proposal A specifies a giant "WEEK 8 OF 15" header with level, progress bar, and countdown. Proposal B uses a dense three-card layout. Proposal C uses a single hero task.

The Phase 2 priority stack is clear: temporal orientation first. The week indicator must be the dominant visual element. But how much of the remaining above-the-fold space goes to status cards versus the primary CTA versus upcoming sessions? The design review shows that when the spec is vague about visual hierarchy, the implementation defaults to a generic date-driven layout. Phase 4 must spec the visual hierarchy in exact detail -- what is largest, what is second, what is below the fold.

Q3: Are submissions and feedback unified or separate?

Three possible models:

The Phase 2 content principle says "items that belong to the same week must be co-located." This favors unification. But the design review shows that the mockup's standalone Submit tab has excellent UX (95% alignment). The question is whether unification into Learn would preserve that UX quality or degrade it by making Learn too complex.

Phase 4 must decide: Is submission a step within the weekly learning flow (unified) or a destination in its own right (standalone)?

Q4: Where does the schedule live relative to other tabs?

Proposal A gives Schedule its own tab (slot 3). This is justified by the Phase 1 finding that the schedule was hidden 5 clicks deep. But the mockup also demonstrates that Schedule is the strongest implementation -- it works perfectly as a standalone tab.

The question is whether Schedule's tab slot is better used for something else. Could schedule be a section within the Today page (next 24-48 hours of sessions) plus a "See Full Schedule" drill-down, freeing a tab slot for Progress? Proposal B's approach (Live tab combining Schedule + Recordings) is worth considering.

Phase 4 must weigh: Is Schedule important enough to justify a permanent tab, or can it be served adequately through the Today page + a secondary access path?

Q5: How does the app handle "you're behind"?

The mockup does not address this. Proposal A acknowledges the risk but does not specify the behind-state design. Phase 2 test L2 requires: visible deficit, one-tap catch-up path, neutral language.

Questions:

Q6: Where does feedback history live?

Three options emerged from the proposals:

The Phase 1 problem brief identifies feedback archives as a hidden feature (currently behind "Hamburger > Feedback History sidebar > month/year filter"). The fix must make feedback browsable without complex filtering. The Phase 2 test C3 requires that Week 6 submission and Week 6 feedback are co-located within one tap.

The question: Is "co-located within each week" sufficient, or does the student also need a flat chronological feed of all feedback? The answer is probably both -- feedback accessible within each week in Learn AND a full timeline in Progress. But this dual-location approach must be designed so it feels like two views of the same data, not two separate features.

Q7: How does onboarding work?

None of the mockup screens address onboarding. The three proposals suggest different approaches: Proposal A mentions an onboarding card on the Today page; Proposal B mentions a "quick setup" prompt; Proposal C specifies a full multi-step guided flow.

Questions:

Coverage Gaps

These are the areas of the User Capability Map at 0% or critically low coverage. Phase 4 must design explicit solutions for each.

0% Coverage -- Must Be Designed from Scratch

Section 4: End of Semester Phase (0/4 capabilities)

The EOC is not a separate screen concept -- it is a state change in the existing architecture. Phase 4 should design it as a special-state week card (Week 15 or "EOC Week") that surfaces in the Learn tab and on the Today page when the student is eligible. Graduation should be a state change in the Progress tab. The Level 4-to-Year 2 transition needs at minimum a clear explanation screen, since the interaction model changes entirely (submissions replaced by appointment booking).

Section 5: Year 2 Differences (0/4 capabilities)

Year 2 may be out of initial scope, but Phase 4 must at minimum design the architecture to accommodate it. The tab bar and information architecture should not need to be rebuilt when Year 2 is added. At a minimum, Phase 4 should identify which tabs change for Year 2 students and ensure the architecture can flex.

Section 3E: Session Recordings (0/4 capabilities)

Recordings need a home. The most natural location is within the Schedule tab (past sessions become watchable recordings) or within the Learn tab (recordings as supplementary material for each week). Phase 4 must decide.

Low Coverage -- Needs Significant Work

Section 2: Pre-Semester Phase (12% -- 1 of 8 capabilities)

Only "Meet assigned Quran Coach" is implemented (via More page). Missing: assessment flow, level placement, program orientation, semester countdown, pre-semester sessions, resource exploration. Phase 4 must design the pre-semester state of the Today page and the onboarding flow.

Section 3F: Progress Tracking (partial -- no grades, no pace comparison)

These require the Progress tab to exist. Phase 4 must decide what "grades" means in context (coaches give qualitative audio feedback, not numeric grades) and how "expected pace" is communicated without shame.

Section 6: Cross-Cutting Capabilities (57% -- missing font settings UI, resources access, community board)

Font settings is a P0-adjacent fix. Resources and Community are lower priority but need a home in the architecture.

Summary Table: Status of Key Architectural Decisions

Decision Proposal A Spec Mockup Implementation Gap Phase 4 Must
Week header format "WEEK 8 OF 15" giant header "Current Week 8" small badge Critical Spec exact visual hierarchy
Level on home screen "Level 4 -- Tajweed Rules" Not shown Critical Include in header
Countdown "3 days until Week 9 unlocks" Not shown High Include below week header
Submission on Today Status card with state + CTA Separate tab, not on Today High Design status card
Tab structure Today/Learn/Schedule/Progress/More Today/Learn/Submit/Schedule/More Structural Make final tab bar decision
Onboarding Mentioned but not detailed Not implemented Critical Design full onboarding flow
Behind state Risk acknowledged, not designed Not implemented Critical Design deficit messaging + catch-up
EOC phase Not specified Not implemented High Design EOC state
Session recordings "Progress > Past Sessions" Not implemented Medium Assign a location
Font settings UI "More > Settings > Display" Menu item only Medium Build settings screen
Journey visualization Not in Proposal A Not implemented Medium Borrow from Proposal C

What Phase 4 Must Deliver

Based on these learnings, Phase 4 (Architecture Specification) must produce:

  1. A locked tab bar with justification for every slot against the Tab Worthiness Criteria.
  2. A complete Today page spec with exact visual hierarchy: what is largest, what is second, what is below the fold. Must include the week header, level, countdown, and status cards. Must pass the 3 Questions Test and the Return Test.
  3. A state model for the Today page covering at minimum: pre-semester, Week 1 (first week), mid-semester (on track), mid-semester (behind), feedback-ready, all-caught-up, EOC-eligible, and post-graduation.
  4. A definitive answer on Submit vs. unified Learn with screen-level detail showing how submission works within whichever model is chosen.
  5. A definitive answer on the Progress tab -- what it contains, how feedback history is organized, and whether the journey visualization from Proposal C is included.
  6. An onboarding flow for the pre-semester phase with exact steps and mandatory versus optional gates.
  7. A behind-state design with messaging, catch-up path, and visual treatment.
  8. An EOC phase design showing how the end-of-course assessment surfaces in the existing architecture.
  9. A location for session recordings within the tab structure.
  10. Coverage targets -- Phase 4 should aim for at least 80% of the User Capability Map at the architectural level (not necessarily mockup-ready, but with a defined home for each capability).