v2 Gap Analysis — Semester Management

Semester Management — V2 Review Gap Analysis

Source: BACKEND-RAMBLINGS.md lines 134-165 Spec: docs/admin-spec/04-semester-management.md Implementation: src/pages/semester-management/

Screens covered

• Semesters list (main)
• Semester Detail — Start Checklist tab
• Semester Detail — End Checklist tab
• Semester Detail — Onboarding Support tab

Semesters list

Matches

• Name, Start Date, End Date columns present and sortable
• Registration status badge (Open/Closed)
• Semester status badge (Active/Draft/Completed)
• Student enrollment count displayed
• Create Semester button with modal form (Name, Start Date, End Date, Registration Start, Content Availability)
• Delete button per row with enrollment blocking (tooltip "Cannot delete: X students enrolled")
• Setup Progress column with visual progress bar and "X/Y" format

Expands

• Stakeholder explicitly mentions needing to edit semesters (change start date, end date, registration dates, etc.). Current spec Section 2.5 only lists View and Delete actions; Create dialog shown but no edit action on existing semesters. Implementation: semesters.tsx has no edit functionality.
• Stakeholder wants auto-transition button that "will start semester, end semester, close and open registration as per the available dates." Spec Section 3.5 has "Auto-Transition (NEW)" toggle in Overview tab, but this is NOT on the main Semesters list. Stakeholder's phrasing ("I need the auto transition button") suggests it should be accessible from the main list view or at minimum highly visible.

Deviates

• None identified.

Adds

• None beyond what spec already covers.

Ambiguous

• Submission Close Date: Stakeholder mentions "Submission close date (we're not intaking submissions any more)" as a field needed in semester setup. Current spec and implementation show: Start Date, End Date, Registration Start, Registration End (implied), Content Availability Date. Submission Close Date is not visible in spec Section 3.5 (Overview tab dates) or in create modal. Needs clarification: is this a needed field, or is it deprecated/handled elsewhere?

Semester Detail — Start Checklist

Matches (structural alignment with spec)

• Setup Checklist tab exists (Section 3.6 in spec)
• Progress bar with "X of Y items configured" format
• Groups: Video Lessons, Assessments, Resources, Live Sessions, Recordings, Tutorials, Quizzes, MCQ Questions, Configuration (Welcome Package, Email Templates, Tags, Teacher Assignments, TA Schedules, Holidays)
• Per-level breakdown for content types (Level 0–4, Year 2)
• Configure links (deep links with ?semester=[id]&level=[level]&from=checklist)
• Items show checkmark when configured, circle when not configured
• Counts displayed (e.g., "12 videos", "14 prompts")
• Expandable preview for first 3 items (inline content preview from Candidate C)

Expands (stakeholder adds detail or changes scope)

• "Semester holidays": Stakeholder lists this as the FIRST item under "Semester start checklist… configuration." Spec Section 3.6 groups it under "Configuration" at the bottom. Stakeholder's emphasis suggests holidays should be more prominent or a separate top-level group, not buried in Configuration.
• "Teacher assignment criteria": Same prominence issue. Spec has it in Configuration group; stakeholder calls it out first.
• Live session schedule: Stakeholder says "Live session schedule" (singular focus). Spec has this (Section 3.6, Group: Live Sessions).
• "One-to-one schedules": Stakeholder explicitly requests "One-to-one schedules." Current spec does NOT include a "One-to-One Schedules" item. Implementation and spec both lack this. TA Schedules (Section 3.6) may map to this, but the label is different and the scope is unclear.

Deviates

• Stakeholder says checklist items should have notes per item: "There should also be a button that allows you to add a note under each one of these." Spec Section 3.6, Actions: "Add Note - Note icon per item (appears on hover) - Opens inline text input below the item." This feature is specified but NOT visible in implementation (setup-checklist-tab.tsx lines 1–250 show no note icon or note UI).
• Stakeholder says items should have a configure button ("When you click, there should be a configure button"). This is worded differently from spec's "Configure -->" link, but they are the same feature. However, stakeholder emphasizes configure as a button, not a link. Minor UX difference.
• Stakeholder mentions "add a setup checklist item for that semester in particular" (ability to add custom checklist items). Spec Section 3.6 does NOT include a feature to add custom items; only "Mark as N/A" and "Add Note" per existing items. Spec allows removing (N/A) but not adding new checklist items. Stakeholder wants extensibility. Gap: custom checklist items not in spec or implementation.

Adds

• Custom checklist items: Stakeholder wants admins to add custom checklist items ("if there's anything else that needs to be added to the checklist, just add it there"). Feature not in spec or implementation.

Ambiguous

• "One-to-One Schedules": Is this a separate checklist item (like TA Schedules), or is it part of TA Schedules? Spec only mentions TA Schedules. Stakeholder calls them out separately, suggesting they are distinct. Need clarification: what is the business difference between TA Schedules and One-to-One Schedules?

Semester Detail — End Checklist

Matches

• Tab does NOT exist in current spec or implementation. Spec describes Close Workflow (Section 3.8) with 5 steps, but "End Checklist" is a different concept.

Deviates

• Structural difference: Stakeholder requests a distinct "Semester end checklist" tab separate from setup checklist. Current spec has:

  • Setup Checklist (Section 3.6)
  • Close Workflow (Section 3.8) — a gated 5-step workflow with approval gates

  Stakeholder's "end checklist" sounds simpler: "The default items on this checklist need to be discussed, but it should also have an option to add custom checklist items."

  Interpretation: Close Workflow (Section 3.8) may be the intended implementation, but stakeholder frames it differently. Close Workflow is gated and step-based; "end checklist" sounds like a simple checklist (similar to start checklist structure) without gates. Spec mismatch in framing.

Adds

• If "end checklist" is separate from Close Workflow: a checklist view with default items (TBD) + ability to add custom items. Spec's Close Workflow is more complex and doesn't support custom items.

Ambiguous

• Relationship to Close Workflow: Is "Semester end checklist" intended as an alternative to the 5-step Close Workflow, or a simplification for non-complex closes? Stakeholder says "default items on this checklist need to be discussed" — suggests items are still being decided. Needs clarification with stakeholder on intended scope.

Semester Detail — Onboarding Support

Matches

• Tab does NOT exist in current spec or implementation.

Adds (entire feature is new to stakeholder, not in spec)

• Telegram/WhatsApp group link management:

  • "A Telegram group link where you can add a Telegram group or a WhatsApp group link and then define which students have access to that."
  • Feature: input field for link URL, control/filter for student access (presumably a permission/role selector or per-student toggle).
  • Not in spec or implementation.

• Welcome videos for new students:

  • "A section for welcome videos where a video can be added to the home screen so new students can see the tutorial upon opening their app."
  • Feature: upload/link video files, display on student home screen.
  • Not in spec or implementation. Note: Spec Section 4 (Welcome Package) includes resources (PDFs, docs, media), but "Welcome Package" is for email/enrollment resources, not on-app tutorial videos.

• Countdown timer (activation/deactivation):

  • "A countdown timer which can be activated or deactivated, showing the start of the next semester for new students who are onboarding."
  • Feature: toggle to enable/disable countdown, auto-calculates time to semester start.
  • Not in spec or implementation.

Deviates

• This is an entirely new tab in stakeholder's conception. Spec has no "Onboarding Support" tab.

Ambiguous

• Student access control for Telegram/WhatsApp: Stakeholder says "define which students have access to that." Does this mean:
  • A dropdown/list of students with allow/deny toggles?
  • A role/group assignment?
  • A level-based visibility rule?
  • Clarification needed.
• Welcome videos scope: Are these pre-recorded onboarding tutorials (e.g., "How to use the app") or semester-specific welcome videos (e.g., "Welcome to Spring 2026")? Affects where/when they display.
• Countdown timer scope: Does it show on a student dashboard, onboarding screen, or both? What time zone?

Mapping note

Current spec structure (Section 3.4, Tab Structure):

1. Overview
2. Setup Checklist
3. Enrollment
4. Close Workflow

Stakeholder's implied structure (from lines 153–165):

1. (Overview — not explicitly mentioned, presumably exists)
2. Semester Start Checklist (lines 153–158)
3. Semester End Checklist (lines 160)
4. Onboarding Support (lines 162–165)

Mapping analysis:

• Overview: Not mentioned by stakeholder but spec has it. Likely continuation of current design.
• Setup Checklist vs. Start Checklist: Same feature. Stakeholder uses "Semester start checklist" (her phrasing); spec calls it "Setup Checklist." Semantic alignment, no structural difference. ✓
• Enrollment: Not mentioned by stakeholder in her narration (lines 134–165). Spec has it as a full tab. Stakeholder's review window may not have covered this, or she's not requesting changes. Absence from her narration does NOT mean removal — silence ≠ removal request.
• Close Workflow vs. End Checklist: Structural mismatch. Spec has a gated 5-step workflow (Section 3.8); stakeholder requests a simpler checklist ("default items… add custom items"). Two different models. Spec's Close Workflow is more comprehensive but more complex; stakeholder's "end checklist" sounds closer to the start checklist pattern.
• Onboarding Support: New tab, not in current spec. Stakeholder adds this explicitly (lines 162–165). Must be added.

Conclusion: Stakeholder's narration maps to a 4-tab structure (Overview, Start Checklist, End Checklist, Onboarding Support), whereas current spec has 4 tabs (Overview, Setup Checklist, Enrollment, Close Workflow).

• Tabs 1–2 align (Overview, Setup Checklist / Start Checklist).
• Tabs 3–4 differ: spec has Enrollment + Close Workflow; stakeholder has End Checklist + Onboarding Support.
• Enrollment tab is not mentioned or requested for removal — likely stakeholder review didn't extend that far, or she considers it orthogonal.
• Close Workflow vs. End Checklist: Close Workflow is more suitable for the complex gated close process. End Checklist (if simpler) could be a separate lighter-weight tab, or End Checklist could be the new name for Close Workflow with some UI simplification.
• Onboarding Support is entirely new and must be added.

Summary

Net-new screens/sections:

• Onboarding Support tab — fully new, includes Telegram/WhatsApp link management, welcome videos, countdown timer
• Custom checklist items for Start Checklist (not in spec)
• One-to-One Schedules item (if distinct from TA Schedules; needs clarification)

Biggest deviations:

1. Tab structure mismatch: Stakeholder expects End Checklist + Onboarding Support; spec has Enrollment + Close Workflow. Close Workflow (spec) may subsume End Checklist (stakeholder) but with different UX (gated vs. simple). Needs design decision.
2. Submission Close Date field missing from semester setup (mentioned by stakeholder, not in spec).
3. Add Note feature specified in spec but not implemented in current code.
4. Custom checklist items requested by stakeholder but not in spec.
5. Edit semester functionality (not on main list or hub) mentioned by stakeholder; spec only covers Create + Delete.

Top ambiguities:

1. End Checklist vs. Close Workflow: Is stakeholder asking for a simplified checklist version, or is Close Workflow the intended implementation reframed as "end checklist"?
2. One-to-One Schedules vs. TA Schedules: Are these the same or different?
3. Submission Close Date: Still needed? Where should it live?
4. Onboarding Support access control: How to assign Telegram/WhatsApp access per student (role-based, per-student toggles, level-based)?
5. Welcome videos display context: Onboarding screen vs. student home screen vs. both?