v2 Review — Framework v2 (Post-Meeting Decision Catalog)
V2 Review — Framework v2
This document is the decision catalog from the Apr 15 stakeholder review. It captures what changes from v1 and why, what was explicitly decided, and what was preserved by silence. It supersedes reference/FRAMEWORK.md (the pre-meeting categorization).
Audiences: Kamran + Lejla (validate decisions landed), sub-agents (build v2 spec from this).
Source material: reference/FRAMEWORK.md (pre-meeting analysis), reference/Apr15-Meeting-Transcript.md (Apr 15 meeting), v1 spec (docs/admin-spec/), gap analyses (reference/01-*.md through reference/09-*.md).
1. Meeting Decision Summary
These 11 decisions were made or confirmed during the Apr 15 review. Each maps to a Framework category and one or more v2 artifacts.
| # | Decision | Category shift | Status | Artifact(s) |
|---|---|---|---|---|
| 1 | Master + semester copy → resolved; Clone-from-Previous is acceptable; add auto-clone on semester create | Cat A confirmed | DECIDED | v2 spec: 04-semester |
| 2 | Registration Tracker → fold into Semester Hub Enrollment as filter preset + co-locate Level 0 promote | D → B | DECIDED | ADR-005 + v2 spec: 03-student, 04-semester |
| 3 | Close Workflow → replaced with flat End Checklist; gated steps become automated backend triggers; stakeholder defines "automatic" per step | C → ACCEPTED | DECIDED (open Qs on "automatic" per step) | ADR-001 + v2 spec: 04-semester + 5 other files |
| 4 | Assignment Criteria → hybrid per-TA matrix + small named rules + preview; drop timezone rule | C → ACCEPTED | DECIDED | ADR-002 + v2 spec: 07-teacher |
| 5 | Communication → 9th domain confirmed; replace community board with announcement board; add 1:1 student↔teacher inbox | D → ACCEPTED | DECIDED | ADR-003 + v2 spec: 11-communication (NEW) |
| 6 | "Send as TA" → rejected; replaced with "admin pre-drafts, TA sends from own account" | D → B | DECIDED | ADR-004 + v2 spec: 11-communication |
| 7 | Tags → keep as-is; bulk email will use tags for filtering | No change | DECIDED | Preserve v1 |
| 8 | Payment Plan grouping → family/scholarship grouped presentation within Plans | Cat A | DECIDED | v2 spec: 08-billing |
| 9 | Subsections not mentioned → preserve from v1; explicitly note "not addressed in review" | New policy | DECIDED | All v2 spec files |
| 10 | Automatic enrollment/billing workflow → parked for later ("park until after app redesign") | No v2 action | PARKED | — |
| 11 | Repeat semester workflow → deferred (meeting ended before discussion) | No v2 action | DEFERRED | — |
2. Framework Categories (Unchanged)
The five-category framework from the pre-meeting analysis remains valid. The meeting resolved all Category C and D items — they are now either ACCEPTED (proceed with decision) or downgraded.
| Category | Risk | Post-meeting status |
|---|---|---|
| A — Refinements | Low | Implement |
| B — Additive Features | Low-medium | Spec addition, then build |
| C — Replacements | HIGH | Both items ACCEPTED — proceed with ADRs |
| D — Structural Additions | HIGH | 1 ACCEPTED (Communication), 2 downgraded (Reg Tracker → B, Send-as → B) |
| E — Deferred | Blocked | Reporting + Issue Queue remain blocked; auto-enrollment/repeat semester parked |
3. Categorization by Domain
Every item from the pre-meeting Framework is preserved below with its meeting outcome. New items from the meeting are marked [NEW from meeting]. Items from the v1 spec that were NOT addressed in the ramblings or the meeting are marked [NOT ADDRESSED] — these are preserved from v1 unchanged.
3.1 Student Management
Category A — Refinements [ALL DECIDED]
- Students list: add gender column; add appointment count column (scope: mastery students, scheduled + completed — confirmed in meeting)
- Student Detail › Submissions: reject-under-review action; copy/download/send recording link buttons; bulk delete via selection
- Student Detail › Submissions: per-week submission exception UI
- Student Detail › Actions: "Enroll in Mastery Course" action
- Failed Sign-ups: "Activate Account" action
- Submissions Management (cross-student): reassign submission action; student name search; submissions close-date picker; gender column; "feedback received" date column
- Student Detail › Appointments: semester filter for past appointments
Category B — Additive Features [ALL DECIDED]
- Student Detail › Admin Notes tab (new tab)
- Submissions Management: 48-hour workday late-response flag
[backend](UI badge + reminder job) - [NEW from meeting] Registration Tracker → folded into Semester Hub › Enrollment as a "Registration" filter preset; Level 0 bulk-promote action co-located there instead of buried in Operations. Downgraded from Category D — see ADR-005.
Category E — Deferred
- None in this domain
Ambiguities [OPEN — carry to v2 spec as TBD]
- "Resend Credentials" on Failed Sign-ups — does this mean temp password or login credentials?
- Appointment time display in student or EST timezone?
- Level 0 bulk-promote target level: ramblings say "level two"; spec says Level 1. Likely stakeholder misstatement; default to spec (Level 1) unless stakeholder corrects.
v1 Sections NOT ADDRESSED in Review These v1 sections were not mentioned in the ramblings or the Apr 15 meeting. Per Decision #9, they are preserved from v1 unchanged.
| v1 Section | Status |
|---|---|
| §3.5 Tab: Profile | Preserved from v1 |
| §3.7 Tab: Payments | Preserved from v1 |
| §3.9 Tab: Semester History | Preserved from v1 |
| §3.11 Cross-Tab Behaviors | Preserved from v1 |
| §5 Promoted Students | Preserved from v1 |
| §7 Cross-Domain Navigation Summary | Preserved from v1 (structural) |
| §8 Data Dependencies and API Calls | Preserved from v1 (structural) |
3.2 Semester Management
Category A — Refinements [ALL DECIDED]
- Semesters list: Edit semester action on each row
- Semesters list: more prominent auto-transition button
- Setup Checklist: implement the existing "Add Note" feature (already in spec §3.6, missing in code)
- [NEW from meeting] Auto-clone on semester create: when a new semester is created, automatically clone content from the previous semester. Clone-from-Previous button remains for manual trigger. (Decision #1)
Category B — Additive Features [ALL DECIDED]
- Setup Checklist: ability to add custom checklist items
- Onboarding Support tab — 3 sub-features:
- Telegram/WhatsApp group link management with student-access scoping
- Welcome videos for home screen
[backend] - Countdown timer to next semester start
Category C — Replacements [ACCEPTED — see ADR-001]
- Close Workflow → End Checklist: Replace the 5-step gated Close Workflow (v1 §3.8) with a flat End Checklist tab, structurally parallel to the Setup Checklist. Gated steps (EOC review, promotions, bulk payment, leavers, verify) become automated backend triggers rather than manual gated steps. Stakeholder to define "automatic" per step. This is the highest-impact single change in v2 — 45 cross-references across 6 files must be updated.
Category E — Deferred
- End Checklist default items: "need to be discussed" — stakeholder deferred defining the specific default items
Ambiguities [OPEN — carry to v2 spec as TBD]
- Submission Close Date field — scope (per-semester/per-level/per-assessment)?
- "One-to-One Schedules" checklist item — distinct from TA Schedules, or same thing?
- Telegram/WhatsApp access control model (role/level/per-student)
- Welcome videos scope (tutorial vs. semester-specific)
- [NEW] "Automatic" definition per End Checklist step — what constitutes completion for each? Backend trigger conditions TBD.
v1 Sections NOT ADDRESSED in Review
| v1 Section | Status |
|---|---|
| §3.5 Tab: Overview | Preserved from v1 |
| §3.7 Tab: Enrollment | Preserved from v1 (but gains Registration Tracker filter preset per Decision #2) |
| §4 Welcome Package | Preserved from v1 |
| §5 Email Management | MOVED to Communication domain (Decision #5, see ADR-003) |
| §6 Tags | Preserved from v1 (Decision #7: keep as-is) |
| §7 Operations (Bulk Actions) | Preserved from v1 (Level 0 bulk-promote action gains a second entry point in Enrollment per Decision #2) |
| §8 Cross-Domain Integration Points | Preserved from v1 (structural, will be updated for cross-refs) |
| §9 Assumptions and Open Questions | Preserved from v1 (structural) |
3.3 Content
Category A — Refinements [ALL DECIDED]
- Video Lessons: multi-video input UI inside a lesson; description field
- Video Lessons: clone-from-previous at semester level (exists in spec; confirm implementation)
- Resources: multi-level tagging (data model tweak:
level→levels) - Resources: support for links and video URLs as resource types
- Recordings: lesson-class vs QRC type column; time-of-day column
Category B — Additive Features [ALL DECIDED]
- Recordings: Zoom auto-upload + auto-tag by level/gender
[backend]— UI affordance needed (sync status, manual override)
Ambiguities [OPEN]
- Assignments location: she described them in Content, spec places them under Student Management. Resolved: keep under Student Management — stakeholder confirmed during content/semester separation discussion (lines 119-145 of transcript).
- Zoom integration UI scope (sync button, pending-review queue, manual override?)
v1 Sections NOT ADDRESSED in Review
| v1 Section | Status |
|---|---|
| §2 Video Lessons (base structure) | Preserved from v1 (refinements above add to it) |
| §3 Resources (base structure) | Preserved from v1 (refinements above add to it) |
| §4 Recordings (base structure) | Preserved from v1 (refinements above add to it) |
| §5 Tutorials | Preserved from v1 — not mentioned in ramblings |
| §6 MCQ Questions | Preserved from v1 — not mentioned in ramblings |
| §7 Quizzes | Preserved from v1 — stakeholder mentioned "we don't need quizzes" (line 30) but did not formally request removal; preserve with note |
3.4 Scheduling
Category A — Refinements [ALL DECIDED]
- Live Sessions: teacher field on create form
- Live Sessions: recurrence + date-range controls (semester start default, end-date override, single-date option)
- TA Schedules: date-bound slots within a semester
- Upcoming Appointments: date range filter; reschedule action
- Calendar: cancel-session, mark-session-inactive, reassign-session actions
Category B — Additive Features [ALL DECIDED]
- Bulk-add live sessions (same name, different times/days/teachers)
- Bulk-add TA appointment slots (same TA, different time slots)
- Cancellation reason templates + send message on cancel
- "Needs replacement" flag on live sessions when TA is on personal break (cross-cutting with TA Holidays)
- One-to-One Appointment Usability dashboard (gender-split slot fill rates; week-by-week underutilized slots; remove-slot button)
Ambiguities [OPEN]
- "Needs replacement" computation: manual, automatic from TA break, or both?
- Gender filter on calendar: TA gender vs. student gender for appointments?
- Bulk-add UX pattern (modal with inline add rows?)
v1 Sections NOT ADDRESSED in Review
| v1 Section | Status |
|---|---|
| §2 Calendar View | Preserved from v1 (refinements above add actions) |
| §3 Live Sessions (base structure) | Preserved from v1 (refinements above add to it) |
| §4 Upcoming Appointments (base structure) | Preserved from v1 (refinements above add to it) |
| §5 TA Schedules (base structure) | Preserved from v1 (refinements above add to it) |
| §6 Holidays | Preserved from v1 — not mentioned in ramblings, but cross-referenced by "Needs replacement" flag |
3.5 Teacher Management
Category A — Refinements [ALL DECIDED]
- Teachers list: semester filter
- Teachers list: live-sessions-per-week and session-slots-per-week metrics
- Teacher profile › Performance tab: average-grade-given metric
- Teacher profile › Performance tab: "submissions received" (total) vs. "reviewed" disambiguation
Category B — Additive Features [ALL DECIDED]
- Teacher Assignment Criteria: per-TA capacity configuration (not a global rule)
- Teacher Assignment Criteria: per-TA level specialization matrix
- Teacher Assignment Criteria: new-vs-returning student routing configuration
- Teacher Assignment Criteria: visual representation of weighted distribution algorithm
Category C — Replacements [ACCEPTED — see ADR-002]
- Assignment Criteria: rules engine → hybrid per-TA matrix: Replace v1's generic rules engine (§4) with a per-TA configuration matrix (capacity, level specialization, new-vs-returning routing) + a small set of named rules (gender match auto, repeat-student auto-assign toggle, distribution strategy). Drop timezone proximity rule — stakeholder confirmed not wanted (transcript line 251). Add read-only preview: "If N students enroll, current config will assign: [TA A]: X, [TA B]: Y."
Ambiguities [OPEN]
- Weighted distribution: deterministic from capacity (auto) or admin-configurable weights?
- Conflict resolution when constraints can't all be satisfied
- Semester binding on Assignment Criteria — entry point is Semester Hub per spec; is that sufficient?
v1 Sections NOT ADDRESSED in Review
| v1 Section | Status |
|---|---|
| §2 Teaching Assistants List (base structure) | Preserved from v1 (refinements above add columns) |
| §3 TA Detail Page | Preserved from v1 |
| §3.4 Tab: Profile | Preserved from v1 |
| §3.5 Tab: Schedule | Preserved from v1 |
| §3.6 Tab: Students & Groups | Preserved from v1 |
| §3.7 Tab: Performance (base structure) | Preserved from v1 (refinements above add metrics) |
| §3.8 Cross-Tab Behaviors | Preserved from v1 |
| §5 TA Reports | Preserved from v1 |
| §6 Student Groups | Preserved from v1 |
3.6 Communication
Category D — Structural Additions [ACCEPTED — see ADR-003]
- Communication as a 9th top-level domain: New sidebar section with 6 screens. Absorbs Email Management from Semester Management and Notifications from Admin & System. Adds 4 net-new screens.
Category B — Additive Features [ALL DECIDED]
- Automation Emails: sequence view (search student → see future email schedule) — absorbed from Semester Management › Email Management
- Blast Emails screen (compose, template library, filter-by-criteria recipient selection) — NEW
- Push Notifications: recipient filtering by level, course, gender, custom tags (enhance existing) — absorbed from Admin & System › Notifications
- Announcement Board screen — NEW (replaces community board concept; one-way communication)
- Private Messages screen (bidirectional student↔teacher inbox) — NEW (confirmed in meeting, transcript lines 253-272)
- Communication Logs screen — NEW
Identity switching → REJECTED; replaced with pre-drafting [DECIDED — see ADR-004]
- Original ask: admin composes, sends "as TA." Meeting outcome: Kamran proposed "pre-draft messages for teachers and they can just hit send" (transcript line 262). Stakeholder agreed this can work. Downgraded from Category D to Category B. No identity switching; admin pre-drafts, TA sends from own account.
Ambiguities [OPEN]
- Sequence view data source (all students vs. sample vs. searched student)
- Template library: unified or separate (automation vs. blast)
- Scheduling: send-now only or future scheduling?
- Bulk email filtering via tags vs. student attributes (transcript lines 274-283 — stakeholder wants both tag-based and manual student selection)
Email Management absorption rules (from meeting discussion):
- Preserve semester-scoping as a filter within Automation Emails
- Setup Checklist deep links from Semester Hub continue to work (they just point to Communication › Automation Emails instead of Semester Management › Email Management)
- Issue Queue stays separate in Admin & System — it is ticketed support, not messaging
3.7 Billing & Payments
Category A — Refinements [ALL DECIDED]
- Family Plans › Family member: per-member discount % field
- Family Plans › Family member: per-member semester status (repeat/regular/mastery) field
- Payment Plans: grouped presentation (Standard / Family / Scholarships / Discounts) — stakeholder wants scholarships and family plans visible within payment plans view (Decision #8)
- Subscription cancel variants on Student Detail › Payments: verify all 4 variants (cancel-now, cancel-at-date, pause-with-unpause-date, send-payment-link) are in UI
[backend] - "Verify Stripe Sync" result modal instead of toast
Category E — Deferred
- None (cancel variants deferred to live Stripe integration but spec'd in v1)
v1 Sections NOT ADDRESSED in Review
| v1 Section | Status |
|---|---|
| §1 Domain Overview | Preserved from v1 |
| §2 Payment Overview | Preserved from v1 (Close Workflow Step 3 reference → End Checklist reference update needed) |
| §3 Payments (Transaction History) | Preserved from v1 |
| §4 Payment Plans (base structure) | Preserved from v1 (grouped presentation adds to it) |
| §5 Coupons | Preserved from v1 — not mentioned in ramblings; stakeholder said "I think I have coupons like separate" (transcript line 316) |
| §6 Family Plans (base structure) | Preserved from v1 (refinements above add fields) |
| §7 Scholarships & Deferments | Preserved from v1 — stakeholder mentioned grouping but then said "I would rather just you know have claude figure it out" (transcript line 307) |
| §8 Cross-Domain Integration Points | Preserved from v1 (structural; Close Workflow refs → End Checklist) |
| §9 Webhook Processing | Preserved from v1 |
| §10 Assumptions and Open Questions | Preserved from v1 |
3.8 Reporting
Category E — Deferred [UNCHANGED]
- All three stakeholder-named categories (financial, student, student composition) need working-session scoping
- Financial reports are not in the current spec at all and would be Category B (Additive) once scoped
- Stakeholder confirmed: "I have to, like, figure out who needs what and kind of Define that. So that's like, needs to be defined." (transcript line 37)
v1 Sections NOT ADDRESSED in Review
| v1 Section | Status |
|---|---|
| §2 Student Report | Preserved from v1 |
| §3 Referrals | Preserved from v1 |
| §4 Specific Reports | Preserved from v1 |
| §5 Student Composition | Preserved from v1 |
| §6 Logs | Preserved from v1 (Communication Logs is a separate screen in new Communication domain, not a replacement for this) |
3.9 Admin & System
Category E — Deferred
- Issue Queue: "Handle it" action semantics; delete vs. resolve distinction; state machine (Resolved terminal? backward transitions?) — UNCHANGED from v1 Framework
Category A — Refinements
- Admins screen: fully covered, no changes needed
Section moves OUT of this domain:
- §4 Notifications → moves to Communication › Push Notifications (Decision #5, see ADR-003)
v1 Sections NOT ADDRESSED in Review
| v1 Section | Status |
|---|---|
| §2 Admins | Preserved from v1 |
| §3 Settings (General) | Preserved from v1 |
| §4 Notifications | MOVED to Communication domain (Decision #5, see ADR-003) |
| §5 Support Links | Preserved from v1 |
| §6 Issue Queue | Preserved from v1 (Cat E — deferred; stays in Admin & System, does NOT move to Communication) |
4. Deep Dive Updates: Category C and D Outcomes
The pre-meeting Framework (§4) contained 6 deep dives for high-risk items. Here are the meeting outcomes for each:
4.1 Registration Tracker — DOWNGRADED to Category B
Pre-meeting: Category D (structural addition — new subsection under Student Management).
Meeting outcome: Not discussed in depth. The execution plan recommends folding into Semester Hub › Enrollment as a filter preset + co-locating Level 0 promote. This avoids:
- Splitting student-list logic across two screens
- Competing with Semester Hub › Enrollment for "who's in this semester"
- Duplicating Level 0 bulk-promote action
Decision: Downgrade to Cat B. Add "Registration" filter preset to Enrollment tab. Co-locate Level 0 bulk-promote there. See ADR-005.
4.2 Close Workflow → End Checklist — ACCEPTED as Category C replacement
Pre-meeting: Category C (replacement). Framework recommended AGAINST replacing — the Step 2→3 gate solves documented workaround W4.
Meeting outcome: Extensive discussion (transcript lines 221-242). Stakeholder's position:
- "I'm not too convinced of all these steps" — she finds the gated workflow too rigid
- Many steps should be "automatic" — e.g., EOC review should auto-close based on submission deadline
- Promotions should be automatic, not manual confirmation
- "We'll remove the gated workflow for 4.3 and then do a checklist" — Kamran's summary (line 242)
- Stakeholder must define "what automatic means" per step
Decision: ACCEPTED. Replace Close Workflow with flat End Checklist. The W4 workaround risk (payment before promotion) is mitigated by making promotion automatic rather than gated. If promotion is automatic, the gate is unnecessary. See ADR-001.
Open questions for stakeholder:
- What constitutes "complete" for each End Checklist item?
- Which steps are fully automatic (no admin action) vs. semi-automatic (admin reviews + confirms)?
- What is the trigger/deadline for each automatic step?
- Does the End Checklist support custom items (like Setup Checklist does)?
4.3 Assignment Criteria — ACCEPTED as Category C replacement
Pre-meeting: Category C (replacement). Framework recommended hybrid approach.
Meeting outcome: Brief discussion (transcript lines 157, 246-251). Stakeholder confirmed:
- Per-TA weighted distribution based on capacity percentages
- No timezone proximity rule ("no no" — transcript line 251)
- The per-TA capacity + specialization model is what she uses today
Decision: ACCEPTED. Hybrid approach from pre-meeting recommendation. Per-TA matrix (primary) + small named rules + preview. See ADR-002.
4.4 Communication as 9th Domain — ACCEPTED as Category D
Pre-meeting: Category D (structural addition). Framework recommended adding with specific rules.
Meeting outcome: Confirmed directly (transcript lines 149, 253-272):
- "I would like to have like a separate section that's just for like all types of communication" (line 149)
- Community board → Announcement Board (one-way)
- Bidirectional student↔teacher inbox confirmed ("we decided to take the risk" — line 257)
- Bulk email critical need ("we don't currently have that as an option at all" — line 273)
- Filtering by tags, gender, level, custom selection (lines 274-283)
Decision: ACCEPTED. 9th domain with 6 screens. See ADR-003.
4.5 "Send as TA" Identity Switching — DOWNGRADED to Category B
Pre-meeting: Category D (cross-cutting structural concept).
Meeting outcome: Rejected during discussion (transcript lines 260-272). Kamran proposed alternatives:
- Automated system for teachers to send reminders (line 260)
- Pre-draft messages for teachers, they just hit send (line 262) Stakeholder agreed pre-drafting could work: "Yeah that can also be like an option" (line 263).
Decision: DOWNGRADED to Cat B. No identity switching. Admin pre-drafts, TA sends from own account. See ADR-004.
4.6 Tags — NO CHANGE
Meeting outcome: Stakeholder initially questioned whether tags subsection was needed (transcript lines 289-305), then contradicted herself ("I need tags for emails"). Kamran pointed out the contradiction (line 294). Resolved: keep Tags as-is. Bulk email will use tags for recipient filtering (line 281).
Decision: No change. Preserve v1 Tags section.
5. Updated Summary Statistics
| Category | Count (v1 Framework) | Count (v2 Framework) | Change |
|---|---|---|---|
| A — Refinements | ~32 items | ~34 items | +2 (auto-clone, plan grouping confirmed) |
| B — Additive Features | ~15 items | ~19 items | +4 (Reg Tracker folded in, Send-as → pre-draft, Communication screens as B after D acceptance) |
| C — Replacements | 2 items | 2 items (both ACCEPTED) | No count change; both now have ADRs |
| D — Structural Additions | 3 items | 1 item (Communication ACCEPTED) | −2 (Reg Tracker → B, Send-as → B) |
| E — Deferred | 3 areas | 5 areas | +2 (auto-enrollment parked, repeat semester deferred) |
Backend-bound tag: ~8 items (unchanged).
NOT ADDRESSED sections: ~30+ v1 subsections preserved unchanged across all domains.
6. ADR Assignments
| ADR | Title | Category | Key risk |
|---|---|---|---|
| ADR-001 | Close Workflow → End Checklist | C → ACCEPTED | 45 cross-refs across 6 files; W4 workaround trade-off |
| ADR-002 | Assignment Criteria → Hybrid Matrix | C → ACCEPTED | Rules engine flexibility loss; weighted algorithm UI complexity |
| ADR-003 | Communication Domain | D → ACCEPTED | 9th domain IA impact; absorbed screens; Issue Queue boundary |
| ADR-004 | Send-as → Pre-drafted | D → B | Downgrade rationale; what remains |
| ADR-005 | Registration Tracker → Enrollment Integration | D → B | Downgrade rationale; Level 0 promote co-location |
7. Close Workflow Impact Radius
The Close Workflow → End Checklist change is the highest-risk edit. Every reference must be updated in v2.
| v1 file | Close Workflow refs | What changes in v2 |
|---|---|---|
| 00-spec-index.md | 7 refs | Nav tree, new screens inventory, WF3 workflow, glossary |
| 01-global-patterns.md | 2 refs | Business rules §7 (linked deactivation context), inline docs §6.3 |
| 02-dashboard.md | 6 refs | Phase prompt tile (semester phase links), alert tiles, data dependencies |
| 03-student-management.md | 2 refs | Student Detail refs to close workflow steps |
| 04-semester-management.md | 26 refs | Complete rewrite of §3.8; cross-domain integration §8 |
| 08-billing-payments.md | 2 refs | Close Workflow Step 3 references in Payment Overview |
| Total | 45 refs | 6 files |