The review, answered — walkthrough v13

• v12 held. Aug 11 confirmed the Today deck, the Learn grid, the lesson player, the submissions archive, the Year-2 lane and the placement flow essentially as built — and raised the mockup's standing: it is now binding on screen content, not just on flow (U-326).
• The student side had one lifecycle and one flow left: submissions (take back until the teacher opens it, a first-class returned state, the attempts cap gone) and booking, redone from the ground up.
• The coach side is the headline. The shape was liked; the size was rejected — "I feel like the coaches app really is missing a lot. It doesn't include like, I'm really not seeing a lot of screens." (U-229). Nine screens became eighteen.

"So the moment they open a submission this becomes locked, so it doesn't have like a 10 minute timer, but it's actually always — you're always able to re-record."

• One state model, student and admin alike — unsubmitted → awaiting review → in review (locked) → reviewed / returned / taken back. Lejla's own list, and her own point that it belongs on the student's screen too, not just the TA's (U-341).
• S25 — the take-back stays available until the teacher opens the submission. The ten-minute countdown is gone, and so is the clock (U-120).
• S60 returned — new. The recording that came back, the teacher's typed reason in her own words, a re-record action, and the line that matters: it does not count against the week, and the week is still open (U-342). Amber and gold, nothing red — a returned recording is not a failure.
• The weekly-attempts cap is removed from every screen — the cap itself, not just the word (U-176). Verified by grep across the build.
• A skipped first-recitation stage travels with the submission so the reviewing teacher sees it and the student never has to explain (U-357). It is shown on C11 — see the adjudicated calls.
• S26 — the "All your feedback" link is gone from the foot (U-371), anchors are confirmed to span a phrase and not only one word (U-370), and feedback finally has a real destination rather than routing to assignments: a labelled Feedback section in the archive (U-372).
• S56 — "From your last review" carries the one or two focus points the coach set last week (U-250). The student half of a promise the coach side now makes.

Before

After

New · S60

Before

After

Before

After

Before

After

"We also most definitely need, on the today screen, a countdown to semester start date. Like, that needs to be there. It needs to be there."

• S07 grew into a Level-0 home — the countdown to semester start, the explainer video pinned until a level is set, the resource kit with a permanent home rather than a one-time appearance, live circles and announcements exactly as a placed student sees them (U-157, U-158, U-360, U-361).
• Today carries the countdown and greys what is not open yet, which is why S18 could be cut (U-171). "Spring 2026 begins in 9 days" sits where Week 8 normally sits.
• Every tab stays visible, with an explanatory empty state — S69 for Assignments ("you'll see your weekly assignments once you're placed in a level") and S70 for Learn, fifteen greyed squares and a quiet way back into the assessment (U-358). Session 3 had said hide the tabs; Aug 11 settled on showing them, and Aug 11 is the later call.
• S05 gains a skip-the-whole-assessment path landing on that same Level-0 home (U-170), and a skipper keeps a persistent "record your first assessment" entry at the top of Today (U-362).
• The pre-semester Today is reachable in app mode too. Verification caught that it was wired to the tour rail only, so a reviewer entering the new-student app and tapping Today still landed in Week 8 — the exact thing U-171 set out to fix. The entrance now sets its own world at boot, which fixes the rail path and the app path at once.
• Policy recorded for the spec, not drawn: a 10-day late intake window, a 24-hour placement target, and auto-placement into Level 2 at week two (U-389). Nobody should sit unplaced long enough for these screens to matter much — but they exist because some people will.

Before

After

Before

After — pre-semester

New · S69

New · S70

"This S33 is really packed, and it's going to look even more packed when we have coaches. It shouldn't be too busy and shouldn't be too disorienting for the student."

• One screen became three — S33 to choose, S62 to commit, S63 when a week is already taken. Progressive disclosure was the explicit ask (U-123).
• S33 — three equal ways in (a teacher, a day, a time of day), because students arrive wanting different things (U-374); a month calendar with opening counts rather than a wall of filters, which is the form Lejla chose when offered a conversational one — "people are really familiar with like the calendar view" (U-380); the horizon is the whole 15-week semester, not the next seven days (U-375); teacher chips shortened so they survive 15 teachers (U-376).
• S62 — the day's open times, a local-versus-chosen timezone control (U-377), and the once-or-weekly choice made on the booking screen itself: "Just Thu 3 Apr" or "Every Thursday" (U-122).
• S63 conflict — new, and the screen that was simply missing: a recurring booking takes the weeks it can, then offers the two nearest alternatives for each week it cannot, plus a skip (U-378).
• Two month calendars — S65 is the booked semester on one page, the most repeated ask of the session (U-127); S64 gives the calendar button in the Sessions header a destination, which it has never had anywhere in the deliverable (U-135).
• S57 — upcoming and past split unmistakably with counts, booking between them (U-345); past 1:1s show date, teacher and notes as text, with no playback, because there is no audio feedback on a 1:1 and there is not going to be (U-130).
• S35 is now the whole appointment — S36's teacher notes moved in so one 1:1 is one screen (U-126); the recurring-versus-one-off badge is gone, since it makes no difference to the student (U-131); and "Reschedule" became "Swap this week's time", the one thing on that page Lejla said she liked (U-132). S71 is the same screen once the session has happened.
• S34 — add to calendar at the moment of booking (U-347), and the way out now goes to the whole list of 1:1s rather than back into one appointment (U-124).
• "1:1" replaces "appointments" as the working student-facing label (U-344) — Kamran raised that "appointments" was wrong, Lejla offered the shorter word.
• S39 stops telling a student in advance what a live session will cover — content is not standardised, so the app should not promise a passage (U-183); live classes launch Zoom, with no in-app player (U-137).

Before

After

New · S62

New · S63

New · S65

New · S64

Before

After

Before

After

New · S71

Before

After

Before

After

"I'm discussing S43 — this has zero information for me… In the You section you need personal information, you need billing information, subscription information — all the things regarding account and enrollment and semester information."

• Today's deck stays (U-328) and the Learn grid stays (U-331) — both confirmed on Aug 11. What went is the leftover Arabic blurb at the foot of both Today screens (U-329). The header now carries the bell alone — the one inbox announcements share with notifications (U-172) — with the fresh-announcement preview at the foot of the screen keeping a second door open (U-164), and a replay of the onboarding sits at the top for the first weeks (U-156). An Aug 11 three-circle quick-access row (U-184) was built first and taken back out on Aug 12: a row of persistent circles is more toolbar than the field guide's "context + local actions" allows. Resources moved to their own row on Learn, where a student looks for materials (U-151).
• S19 was rebuilt around real daily practice — warm up the letters, read aloud, listen and follow — instead of a generic rest-day agenda, and it says plainly that none of it is recorded or counted (U-173).
• Lessons and submissions never share a screen (U-174), and the record CTA came out of the lesson player (U-175). Flagged because it was live in v12: the player carried "Your recitation for this week" under the video set, which is precisely the pairing Lejla talked herself out of. The foot of S21 is now notes, practice card and transcript, and nothing else.
• Cards read as objects. The one concrete piece of the visual-identity conversation, taken now: "sometimes when it's like a white box on white background it's hard to see that it's a box" (U-179). The page sits back and the cards sit on it — clearest on S21 below. The ground this introduced is the app's own plum at 3%, #FAF7FA, and it is deliberate and app-wide: it is why v13 screens read slightly warmer than v12's white in every pair on this page.
• S45 messages says whose thread it is. Messaging is scoped — Year 1 to the designated coach, Year 2 only to the teachers she has booked (U-351) — so the header names the relationship instead of promising a reply time; the way in no longer depends on an appointment (U-139); and the composer states plainly that both sides are notified, on sending and on replying, which is the live complaint (U-140). Where messaging ultimately lives is still open (U-163).
• S61 Resources — new, with a permanent place of its own, doored from Learn since Aug 12 (U-151); S68 Previous levels puts earlier levels' videos, lessons, submissions and feedback inside the learning space rather than the account, across semesters and years (U-143).
• The You tab got real substance — S66 subscription and billing (U-152), S67 learning history redefined as previous enrollments rather than submissions (U-142). Removed: the "View the coach app" row, which nobody could explain (U-146), and the coach's welcome voice note, which belongs to onboarding and not to a settings screen (U-155). Added: Join Telegram under Support (U-148). Announcements are filterable by level (U-147).
• No Quran font setting — one mushaf-matched face, no choice (U-153). This one was decided once before and re-decided here: "you remember our font struggles."
• The tab bar is five, confirmed: Today, Learn, Assignments (submissions and feedback), Sessions, You (U-161).

Before

After

Before

After

Before

After

Before

After

Before

After

Before

After

Before

After

Before — scrolled

After — scrolled

Before

After

New in the learning space and the account

S61 resources

S68 past levels

S66 subscription

S67 learning history

"I feel like the coaches app really is missing a lot. It doesn't include like, I'm really not seeing a lot of screens."

The coach lane had never been reviewed before this round. It was reviewed once, live, and audited once in writing against a survey of eleven coaches. The shape survived — a queue, a review, a roster, a record. The size did not: nine screens became eighteen.

The review flow, where the P0s were

• Notes are on the review screen — Radwa, in the survey: "I have to write separate notes so I can remember the mistakes the student made." Writable and readable where the review happens, not one tab away on the student record (U-247).
• The player persists with scrub and speed, and stays with her as she scrolls to the notes (U-246) — which also answers the defect where comments were unreachable without split screen (U-308).
• Autosave and resume on a half-recorded take, so a freeze, an incoming call or a weak signal does not cost the whole review (U-248).
• One or two focus points carry forward — into her next review of that student, and onto the student's S56 before she records (U-250).
• Nothing truncates. Every note, message preview, announcement and hours reason wraps in full; the cut-off comment display is carried as a regression test (U-305, U-307).

The tab bar — and what it costs

• Home · Queue · Students · Appointments · Schedule. Appointments was asked for by name ("so many teachers do both", U-196); Schedule shrank to live classes only, because Lejla wanted everything appointment-related in one place (U-205); and C10, a role-adaptive home, goes ahead of the queue because three of eleven coaches review no submissions at all and were opening the app on an empty list (U-285).
• The named cost: You moved off the tab bar, behind the avatar on C10's header. Five slots were full and the four above are all daily work. A coach looking for her settings, her hours or the way back to her student app will look at the tab bar first, and it will not be there. This is a real regression in findability, traded for four destinations she needs every day. Reversible — say the word and Schedule or Students moves behind the avatar instead.

Notes: two tiers, and nothing called private

• Student notes (the student reads them) and coach notes (attached to the profile, readable by any coach assigned to that student, surviving reassignment) — the decided model (U-253, U-193). Every note surface names its audience: "Sarah reads these" / "every coach assigned to her".
• A reversed reconciliation verdict, named out loud. The reconciliation board ruled that the review screen's "For Sarah / Private — just me" audience toggle was "a specific, named coach requirement; its absence is a functional gap, not a simplification", and v12 restored it on that basis. v13 removes it. Lejla settled both halves in the coach session: coach notes are readable by any teacher assigned to that student, so calling anything private is misleading — "the private note is actually coach's notes, which is any, any teacher can view" (U-194) — and there is no private-to-me tier at all (U-258). Gone with it: the audience state, the "Save private note" action, and the "Just for you — not sent to Sarah" line. Send is now unconditional, which is also the simpler seam. The word "private" appears nowhere in the coach lane.
• Also removed, same reasoning: "Your hours log automatically." True of the old model, wrong under C16, where hours are logged for her and correctable by her.

Roster and record

• C04 became a workload view — what she owes this week, not who her students are: overdue, due this week, days since the last feedback (U-261), plus per-student submission counts and current-semester score without opening anyone (U-208), the semester each student is in (U-197), and a pass/fail control that sits greyed behind a padlock until the EOC opens in the last two weeks (U-210).
• C05 is chronological — submissions, feedback, 1:1s and attendance in one scroll (U-257), with tenure and accumulated mistake history (U-255) and a listened / not-listened receipt on each piece of feedback, which was Sana's ask: "I don't know if the student has even listened to the feedback" (U-259).
• How far C04 goes beyond this stays open pending coach input (U-198, U-202) — the audit is evidence about how coaches work today, not a design review of C04 as drawn.

Before

After

Before

After

Before

After

Before

After

Before

After

Before

After

Before

After

Seven new surfaces

• C10 Coach Today — her day first, the queue second (U-285).
• C11 Placement — first assessments leave the general queue for a role-gated screen with a level control, because placement produces a level, not feedback (U-252). Consistent with the placement-only policy settled in v12.
• C17 Appointments — every 1:1, past or upcoming, openable to write its notes or message that student (U-206). The tab both reviewers asked for.
• C16 Hours — in-app tracking replaces Time Clock Wizard (U-221): all three work types, manual add and subtract with a one-line reason (U-222, U-223), an optional timer (U-224), a period total with its approval state, correctable until the period closes, and a finance export (U-281). Built whole deliberately — anything partial and Time Clock Wizard survives alongside the app, which the audit calls the worst outcome (U-284).
• C14 Curriculum — the whole lesson catalogue, not just her level (U-233); per-level weekly topics available while she reviews (U-235); copy a lesson link straight into feedback so the student taps through (U-236); weekly text and PDFs and prep notes in one place (U-289) and a reusable teaching-resources library, so preparation is not unpaid labour (U-291).
• C15 Messages — her inbox for students and a channel to the program team. Alaa's line was the case for it: "not able to communicate with student if they or me couldn't get in the zoom meeting" (U-292). Threads work with or without an appointment (U-293, U-294).
• C18 Announcements — posted in her own name, targeted by level, gender, semester and year, so a late class is announced by the person who is late (U-217, U-218).
• Smaller: she can edit her own picture and description on C09 (U-226); there is no coach-to-coach handover anywhere, because that is an admin action (U-216).

C10 home

C11 placement

C17 appointments

C16 hours

C14 curriculum

C15 messages

C18 announce

Two things to look at with a veto in hand

• "Return this recording instead" is an addition beyond the spoken asks. S60 — the returned recording on the student side — needed an author, and nothing in the coach lane could produce that state. So the review screen gained a quiet action under Send: a one-line written reason, and it goes back without counting against her week (U-341, U-342). Nobody asked for it in those words. It is one block to delete if the coach side should stay read-only on that state.
• The unresponsive control is a best guess. Lejla, in the coach entrance: "Why is this not working?" (U-232). The likeliest culprit found and fixed is C01's filter pills — a selection toggle that never re-sorted the rows; each filter now carries its own comparator. Two other dead affordances went with it: "Anchor another word" (a button that could not add an anchor) and "Re-record" (which now really clears the note). Worth confirming against her recording that the pills were what she tapped — if it was something else, that something is still broken.

Both are drawn, both carry a gold "Proposal — decision needed" banner on the screen itself, and nothing else in the build depends on either. They are on the map because Lejla asked for the coach feedback to be incorporated so she and Yasmine can re-review it — not because the call has been made.

• C12 · a student reply channel. Five of eight coaches asked for a way for a student to respond to feedback. The audit is careful about what that is not: "What coaches are describing is a reply channel, which is a different feature: not re-graded, not re-scored, doesn't touch the week's evaluation" (U-295). The grading objection that retired retakes stays intact (U-301). Blocking: is it in or out, and what workload does it create for coaches — currently unscoped (U-306).
• C13 · a live-class surface. "Eight of eleven coaches teach live classes and the coach lane has nothing for them" (U-287) — roster, attendance, a session timer and a speaking-turn tracker. Blocking, in the audit's own words: "Do live classes get a coach surface in v1, or stay on Zoom plus Google Sheets? Eight of eleven coaches teach them; the answer materially changes the size of the build" (U-321).

Proposal · C12

Proposal · C13

"I'm worried that they will not figure out what the screen number is below the screen." — Kamran: "Maybe next to the time…"

• The screen code is in the phone's status bar, where the clock would be (U-397), and it stays in step when a reviewer taps through the app instead of advancing the rail — which is what went wrong when the rail said S17 and the screen was the You tab (U-186).
• The build version and date are stamped visibly (U-169).
• Navigation is free — move between screens without restarting (U-385); the dead Today tab on the Year-2 lane works (U-349); vertical scrolling is allowed, so a screen may be longer than one viewport (U-185).
• Report an issue is drawn as an app feature for launch — a floating affordance that can carry a screenshot (U-145). It is a product decision made visible, not a walkthrough control.
• The stripped TA landing — a page that is only the four entrance cards, with no surrounding explanation, for Lejla to hand to the teaching staff (U-396). It is part of the hub, not this build; it lands with the deploy.

Decisions I made because the evidence pointed one way and nobody had made them explicitly. All reversible.

• S40 is cut. Session 3 said rebuild it as the booked-appointments week its own annotation promises, "or cut it" (U-128). Between the 1:1 tab's own calendar (S65) and the Sessions month view (S64), everything a rebuilt S40 would do already has a home. Code retired.
• S18 is cut — asked directly (U-171). The ordinary Today carries the countdown and greys what is locked, so a separate pre-semester screen would be a second Today.
• S36 is folded into S35 so one appointment is one screen (U-126). Its payoff is S71, the past 1:1 where the notes live.
• "1:1" is the working label (U-344), applied across the student side now. Final wording is still Yasmine's — and the spelled-out "One-to-one with Ustadh Kareem" survives inside cards and rows, because that is the long form rather than the word being replaced.
• The visual-identity pass is parked to its own round, on Kamran's own framing from Aug 11: judge each screen on flow and content, and hold subjective character separately (U-327). Yasmine's "I feel like there's zero character to it" (U-165) is not dismissed — it is the next design phase, with the five-words exercise. v13 takes only the concrete piece (U-179).
• The skipped stage shows on C11, not on C02/C03. The flag travels with the first-assessment recording, which is the only recording that has stages; a "part skipped" line on a weekly review would invent a state the student side cannot produce. The student-side promise is kept by C11 (U-357).
• The 75%-of-Zoom auto-mark is not adopted (U-263) — it was a survey wish, and Zoom is third-party. Attendance stays coach-marked on C08 and C13, and the copy says why.

• Codes are pinned properties, not positions: a code is assigned once and belongs to that screen for good. Retired codes are never reused; new screens only append. package.ts fails the build if a chapter has no code, if two share one without sharing a screen, or if a retired code reappears.
• The tour is now 82 chapters (64 in v12). The coach lane runs C01–C18 across two acts, THE COACH SIDE and the new COACH TOOLS.

Retired this round

New in v13 — student

New in v13 — coach

• Kamran: read this page, then step the entrances in handoff/walkthrough/QuranFlow-Walkthrough.html (double-click, offline — the coach entrance is the one that changed most). Approve, and it commits, pushes both remotes and redeploys the hub. This page then lives at /changes-v13/; v12's stays where it is at /changes/, because Lejla already holds that link and it should keep showing what it showed. The flow map stays at /flow-map/.
• Then Lejla and Yasmine re-review the flow map. This was her explicit condition: tell her when the coach feedback is on the map, and the two of them will go through it again. That re-review is the gate on the coach lane, not this document.
• Then the TA round runs on this build — narrated voice notes that Lejla transcribes, with light coaching on how to record them (U-398), and the TAs told plainly that this is not a copy review (U-399). Lejla and Yasmine then recheck independently (U-401). The stripped four-card landing (U-396) is what they get handed.
• Owed back to us: Yasmine's separate document on TA feedback the app does not yet address (U-241), and her screen-by-screen copy pass, which every wording in this build is waiting on.
• On our side: sync PRODUCT-SPEC.md and DATA-MODEL.md across both rounds, and delete the three registered but unchaptered screens (recording-noattempts, week-at-a-glance, appointment-notes) once v13 ships.
• The hub stays the single always-current copy — nothing newer exists anywhere, which is why the link is the thing that gets shared (U-403).