v2 Review — Pre-Meeting Framework (5-Category Risk Model)

V2 Review — Categorization Framework

This document proposes a framework for triaging the stakeholder feedback captured in BACKEND-RAMBLINGS.md against the existing spec (docs/admin-spec/) and mockup implementation (src/pages/). Each item is classified by its risk to the evaluated architecture of the spec, so we know what to build directly, what needs clarification, and what needs an architectural decision before we touch it.

The working principle: the spec is not arbitrary. Enhanced Candidate A was selected via structured multi-candidate evaluation in WS1.5 (scoring 30/35, top of 3 candidates), and specific mechanisms inside it — gated Close Workflow, 8-domain sidebar, entity detail pages — were designed to solve documented admin pain points with quantified workflow improvements. Changes that touch those mechanisms carry a risk of regressing the workflow benefits that justified the redesign. Changes that don't touch them are low-risk additions.

1. The Framework: 5 Categories + Tags

Category A — Refinements

Small additions or modifications that build on existing spec items (new columns, new filter options, new fields, new action buttons, label changes). Don't touch the IA or the workflows.

Category B — Additive Features

Net-new capabilities that stack on top of the existing IA without changing it. New tabs within existing entity pages, new subsections within existing domains, new fields or data concepts that don't disturb the shape of the product.

Category C — Replacements / Reframings

Stakeholder proposes a different model for something the spec already solves. The spec's model was chosen for documented reasons; her model may or may not preserve those benefits. These require an explicit architectural decision with rationale, not a default swap.

Category D — Structural Additions

Introduces a new top-level domain, new first-class sub-nav, or a cross-cutting concept (identity, audit trail) that changes the evaluated IA. These alter the mental model that the WS1 scoring was based on.

Category E — Deferred

Stakeholder explicitly punted. Blocks building until she defines the scope.

Tag — Backend-bound

Orthogonal to the 5 categories. Marks any item whose real behavior requires backend/integration work beyond the mockup. In the mockup we show the UI affordance; production does the actual work.

2. What's Changed From My Earlier Analysis

After re-reading the spec with the content-vs-semester separation confirmed as intentional, two items I had flagged as "structural" collapse:

Item Earlier classification Revised classification Why
"Master + per-semester copy" pattern for content Structural — new data model Category A (Refinement) The spec already has Clone from Previous (semester hub §3.6, welcome package §4.5, email management §5.5) with OQ5 resolution of "independent copies." This is effectively what she's describing, just phrased differently. No new data model required.
Assignments appearing in Content domain Structural — missing screen Ambiguity Spec deliberately places Submissions under Student Management (student activity) and keeps Content for passive curriculum materials. Her placement in Content is likely a narrative slip, not an IA change.

These reclassifications reduce the "high-risk" count meaningfully.

3. Categorization by Domain

A compact catalog. Every ask in BACKEND-RAMBLINGS.md maps to exactly one category. Backend-bound items are marked with [backend].

3.1 Student Management

Category A — Refinements

Category B — Additive Features

Category D — Structural Additions

Category E — Deferred

Ambiguities

3.2 Semester Management

Category A — Refinements

Category B — Additive Features

Category C — Replacements

Category E — Deferred

Ambiguities

3.3 Content

Category A — Refinements

Category B — Additive Features

Ambiguities

3.4 Scheduling

Category A — Refinements

Category B — Additive Features

Ambiguities

3.5 Teacher Management

Category A — Refinements

Category B — Additive Features

Category C — Replacements

Ambiguities

3.6 Communication

Category D — Structural Additions

Category B — Additive Features (contingent on D above)

Ambiguities

3.7 Billing & Payments

Category A — Refinements

Category E — Deferred

3.8 Reporting

Category E — Deferred

3.9 Admin & System

Category E — Deferred

Category A — Refinements

4. Deep Dive: Categories C and D

For each Category C (Replacement) and Category D (Structural Addition) item: what the spec currently does, why it was designed that way, what her ask implies, second-order impacts, and a recommendation.

4.1 New Semester Registration Tracker (Category D, Student Management)

Her ask: A dedicated subsection under Student Management, shown during the registration window. Lists both returning and new students enrolling in the upcoming semester. Columns include current level, previous level, registration semester, enrollment date, first-assessment-sent indicator (for Level 0), status (graduate/repeat/new). Key action: filter Level 0 students without first assessment → select all → bulk promote to Level 2 (the spec says Level 1 — confirm which).

What the spec currently does:

Why it was designed this way: The redesign consolidates student-state views on the Student Detail page (6 tabs — workflow WF2 reduced from 5-7 screens to 1-2). The Semester Hub's Enrollment tab gives per-semester visibility inside the semester context. The Level 0 bulk promote is an operation, placed with other operations.

What her ask implies:

Second-order impacts:

  1. Splits student-list logic across two screens (Students and Registration Tracker). Admins need to know which to use when.
  2. Competes with Semester Hub › Enrollment for the "who's in this semester" question. May confuse WF1 (Semester Setup) workflow.
  3. The Level 0 bulk promote action is already surfaced in Operations; moving or duplicating it here creates two entry points to the same action.

Recommendation:

4.2 Appointment Count column on Students List (Ambiguity, Student Management — not strictly Cat C/D but worth flagging)

Her ask has a subtle scope issue: "for mastery course students, the number of meetings and number one-to-one appointments." Could mean (a) a column visible only for mastery students, (b) a column aggregating across all students, or (c) two columns. Decide before implementation — the spec has a single student list.

4.3 "End Checklist" in place of Close Workflow (Category C, Semester Management)

Her ask: A "Semester End Checklist" tab on Semester Hub — a simple flat checklist with default items (TBD) and ability to add custom items. Parallel in structure to the Start Checklist.

What the spec currently does:

Why it was designed this way: The gate between Step 2 and Step 3 is load-bearing. It is the direct solution to documented workaround W4 in 04-semester-management.md: "Payment setup done before promotions finalized — tracked in Stripe Dashboard + guesswork → Close Workflow gate between Step 2 and Step 3." This specific mechanism was called out in WS2 billing discovery. The quantified workflow improvement is WF3: Semester Close reduced from 8+ screens / 40-70 clicks / 3 external tools to 4-6 screens / 15-25 clicks / 0 external tools (00-spec-index.md §6, §10).

What her ask implies: Replacing the gated workflow with a flat checklist discards the Step-2→Step-3 gate. Without the gate, nothing stops the admin from setting up payments before promotions are finalized — which is the exact pain point the redesign was built to fix.

Second-order impacts:

  1. Reintroduces workaround W4 (payment before promotion) — the WS2 billing pain point.
  2. Regresses WF3 workflow improvement — the measured 38-50% screen reduction is partly attributable to the gated sequence eliminating redundant back-and-forth.
  3. Loses the linked-deactivation workflow (Step 4) unless custom items are added — custom items in a checklist don't carry the same structured semantics (confirmation modals, Stripe API orchestration, audit logs) as spec'd steps.
  4. Loses Step 5 verification dashboard, which catches unresolved exceptions before the semester is marked closed.

Recommendation: Do not replace Close Workflow with a flat checklist. Two options that address her likely underlying concern:

This is the single highest-risk item in the review. Push back explicitly before swapping.

4.4 Assignment Criteria — Rules Engine vs. Per-TA Matrix (Category C, Teacher Management)

Her ask: Per-TA-per-semester configuration of capacity, level specialization, new-vs-returning routing, plus a weighted distribution algorithm ("if one TA can take 10 and another 50 and we have 6 total, split 1:5").

What the spec currently does:

Why it was designed this way: The spec's rules engine is flexible — any combination of constraints can be expressed. It was framed as a configuration-light system consistent with the admin's stated preference for automation (WS1 Q4: "I would group things by what they're about").

What her ask implies: A per-TA matrix is more declarative and legible for this admin's mental model ("TA Smith handles Level 1–2 female students, max 12"). The weighted distribution algorithm is a specific behavior with a specific rule ("fill each TA's capacity proportionally"), not a generic rule that can be tuned.

Second-order impacts:

  1. Replacing rules with a matrix loses flexibility (what if a new routing dimension comes up?).
  2. Two paradigms side-by-side (rules + matrix) increases UI complexity and can create conflicts.
  3. The weighted distribution algorithm needs somewhere to live. Pure matrix doesn't express it; pure rules engine doesn't either. Could be a separate "Distribution Strategy" setting on top.

Recommendation: Hybrid approach:

This is a substantial spec expansion (07-teacher-management.md §4 needs rewriting) but not a full regression — the matrix is additive to what exists.

4.5 Communication as a 9th Top-Level Domain (Category D, Communication)

Her ask: A dedicated Communication section in the sidebar with 6 subsections (Automation Emails, Blast Emails, Push Notifications, Announcement Board, Private Messages, Communication Logs), plus identity-switching (§4.6 below).

What the spec currently does:

Why it was designed this way: Email Management sits under Semester Management because emails are semester-scoped (welcome emails for Spring 2026, promotion emails tied to that semester's close). Notifications is under Admin & System because broadcasts are operational tools. The spec didn't scope bidirectional messaging or an announcement board — those are effectively new product surfaces.

What her ask implies: Adding 4-5 new screens (blast email, announcement, private messages, logs) plus sequence-preview for automation emails. If these all go under a new Communication domain, that's a 9th top-level item.

Second-order impacts:

  1. IA change: Enhanced Candidate A was evaluated as "8+1 domains" (8 domain sidebar + Dashboard). The WS1.5 scoring was based on this mental model. A 9th domain isn't disqualifying, but it warrants a sidebar re-review (do other domains feel crowded? is the admin's mental model still a match?).
  2. Email Management: Currently under Semester Management because emails are semester-scoped. If Automation Emails moves to Communication, the semester linkage becomes a filter rather than a nav structure. Defensible but non-trivial.
  3. Logs: Already a screen under Reporting (Reporting > Logs). A Communication Logs screen creates two logs locations. Should they be unified, linked, or kept separate?
  4. Issue Queue overlap: Private Messages (bidirectional admin-student) overlaps in purpose with Issue Queue. The distinction (Issue Queue = ticketed support with priority/status; Private Messages = conversational) needs to be drawn explicitly or the two should be merged.

Recommendation: Add Communication as a 9th domain with these rules:

4.6 "Send as TA / Send as Admin" Identity Switching (Category D, cross-cutting)

Her ask: Any outbound communication (email, push, announcement, private message) can be composed by an admin but sent "in the name of" a specific TA or another admin.

What the spec currently does: Nothing. Communications are implicitly sent "from QuranFlow" or similar.

Why it wasn't in the spec: Not surfaced in WS1/WS2 interviews. The redesign focused on consolidating information surfaces, not on communication identity.

What her ask implies: A "Send as" selector on every communication form, plus a backend audit trail (who composed vs. who was named as sender). Also a policy decision about reply routing.

Second-order impacts:

  1. Audit trail: Every communication needs composed_by and sent_as fields. Communication Logs must surface both. Permissions (who can send as whom) must be defined.
  2. Reply routing: If student replies to "Ahmed" (TA), where does the reply go? Ahmed? The composer? Both? Current Email Management doesn't handle replies at all — this adds an inbox concept.
  3. TA awareness: Should the TA be notified that an admin sent something in their name? If not, TAs can be impersonated without their knowledge.
  4. Deactivated TAs: If a TA leaves, do their historical sent-as messages retain the name or redact?
  5. Cross-domain impact: This concept bleeds into Billing (payment reminders "from Ahmed"?) and Scheduling (cancellation messages). Scope creep risk.

Recommendation: Treat this as a Category D structural decision, not a Category B feature. Before implementing:

This is a real product concept (it's common in CS tools), but it's new scope. Worth a separate conversation before building.

5. Summary Statistics

Category Count Risk Action
A — Refinements ~32 items Low Implement after brief confirmation
B — Additive Features ~15 items Low-medium Spec addition, then build
C — Replacements 2 items (End Checklist; Assignment Criteria shape) HIGH Architectural decision with rationale
D — Structural Additions 3 items (Registration Tracker; Communication domain; Send-as identity) HIGH Re-evaluate against WS1 workflow analysis
E — Deferred 3 areas (Reporting; Issue Queue; End Checklist default items) Blocked Working session

Backend-bound tag: ~8 items (Zoom sync, Stripe variants, email sequencing engine, late-SLA job, InfusionSoft, audit trail for Send-as, push delivery tracking, webhook-cached billing alerts).

6. What This Means for a New Spec

Nothing in Category A or B threatens the existing spec's benefits. Most of the ramblings can land as additions or refinements to current spec sections.

The 2 Category C items are where we can regress the workflow analysis. Close Workflow especially is load-bearing and the gate must be preserved. Assignment Criteria shape is flexible but needs decision before redesign.

The 3 Category D items expand scope and/or restructure IA. They warrant revalidation of the 6 workflow analyses in 00-spec-index.md §6 — especially WF1 (Semester Setup) and WF4 (Daily Monitoring), which touch Communication and Registration flows.

Proposed sequence:

  1. Resolve Category C items via architectural decision with her (§4.3, §4.4)
  2. Resolve Category D items via architectural decision + WF revalidation (§4.1, §4.5, §4.6)
  3. Unblock Category E with working sessions (Reporting, Issue Queue, End-checklist items)
  4. Update docs/admin-spec/ with the decisions
  5. Build Category A and B items against the updated spec

Only after steps 1-4 should any implementation work start — the risk of building to the wrong spec is higher than the cost of the decision-making sessions.