v2 Gap Analysis — Teacher Management

Teacher Management — V2 Review Gap Analysis

Source: BACKEND-RAMBLINGS.md lines 234-269 Spec: docs/admin-spec/07-teacher-management.md Implementation: src/pages/teacher-management/

Screens covered

(Stakeholder does not mention TA Reports or Student Groups — these remain per spec; not analyzed here.)

Teachers list

Matches

Expands

Stakeholder requests exact stats, current spec matches:

Deviates

Adds

Ambiguous

Teacher profile / Detail

Matches

Expands

Stakeholder requests exact performance stats — current implementation includes:

Also requests stats already shown in list:

Deviates

Adds

Ambiguous

Teacher Assignment Criteria

Major section spanning lines 263–269 of stakeholder narration. Current implementation shows a rules-based system; stakeholder describes a criterion-driven, configuration-heavy system with algorithmic weighting. High complexity gap.

Matches

Expands

Stakeholder specifies granular configuration elements:

Missing from current implementation:

  1. Semester-specific criteria configuration (line 265)

    • Current: Single global rule set, no semester selector
    • Expected: "Add a semester teacher assignment criteria" — admin selects semester, then configures rules for that semester only
    • Spec mentions this implicitly (entry point: "Semester Hub > Setup Checklist")
    • Gap: No UI for "which semester is this rule set for?"

  2. Gender matching (line 266)

    • Current: Generic "Gender Match" rule present, description mentions it
    • Stake holder specifies: "automated to simply match TA gender to student gender"
    • Gap: No clear UI for admin to understand or configure this. Is it automatic or configurable?

  3. Max student capacity per TA (line 267)

    • Current: Generic "Balanced Load" rule mentions "max 10 students per TA"
    • Stakeholder: "maximal student capacity for the semester for each TA" — implies per-TA, per-semester capacity settings, not global
    • Gap: Capacity should be configurable per TA, not just a global rule. Where does admin set "TA A can take 8, TA B can take 50"?

  4. TA level specialization (line 267)

    • Current: Generic "Level Specialization" rule mentioned
    • Stakeholder: "which TAs are dealing with which levels" — needs explicit configuration per TA
    • Gap: No UI to map "TA X handles Level 1 & 2, TA Y handles Level 3" or to show this matrix.

  5. New vs. returning student routing (line 267)

    • Current: Repeat student auto-assign toggle only
    • Stakeholder: "which TAs are dealing with new students and which are dealing with repeat and graduate students"
    • Gap: Needs explicit TA → student-type routing config. Is TA A only for new students? TA B for repeats? Should be configurable and visible.

  6. Weighted distribution algorithm (line 269)

    • Current: Rules system with priority; no explicit weighted algorithm UI
    • Stakeholder: Detailed example: "If one TA can take 10 students and another TA takes 50, and we have 6 students in total, they should be distributed fairly so that everybody gets their 20% filled out. The one that's taking 10 students gets 1 student and the one that's taking 50 students gets 5 students."
    • Gap: MAJOR AMBIGUITY
      • Is this algorithm automatic (computed at enrollment time)?
      • Or must admin enter weights manually?
      • How is this visualized? Is it:
        • A read-only calculation preview ("if 6 students enroll, distribution will be: TA A gets 1, TA B gets 5")?
        • Configurable weights that admin enters ("TA A weight = 0.2, TA B weight = 0.8")?
        • Just capacities, and algorithm handles the rest behind scenes?
      • Stakeholder description is mathematically clear but doesn't specify UI interaction.

Deviates

Adds

Ambiguous

  1. Weighted distribution algorithm presentation (critical)

    • How should admin interact with the weight formula?
    • Is there a visualization showing the expected distribution?
    • Example: If TA A capacity = 10, TA B = 50, and 60 students enroll, should UI show:
      • "Fair split: 10 to A, 50 to B" (read-only)?
      • Or allow admin to adjust weights?
    • Recommendation: Clarify whether this is deterministic (auto-calculated from capacity only) or admin-configurable (requires weight input).

  2. Per-TA configuration surface

    • Stakeholder wants per-TA-per-semester settings (capacity, level, student type).
    • Current implementation is global rules.
    • Where does admin configure "TA Smith handles Level 1–2, TA Jones handles Level 3"?
    • Is this done on the TA Detail page, or within Assignment Criteria?
    • Current gap: No per-TA matrix/table to edit capacity, level, and student-type assignments.

  3. Semester binding

    • Stakeholder: "semester specific" — rules should apply to one semester only.
    • Current: No semester selector visible in Assignment Criteria UI.
    • Gap: Unclear if rules are globally applied or if there's a hidden semester context.

  4. Conflict resolution

    • Stakeholder prioritizes: "student is assigned to the same gender teacher who handles their level and handles new or returning students."
    • Multiple constraints (gender, level, student type, capacity, weighted distribution).
    • Ambiguous: If all constraints can't be met (e.g., no female TA handles Level 3 for new students), what's the fallback? Current rule system doesn't express this hierarchy explicitly.

Summary

Net-new screens/sections:

Biggest deviations:

  1. Live session metrics missing from teacher list and profile (2 metrics: sessions scheduled, session slots available)
  2. Average grade given metric missing from Performance tab
  3. Teachers list lacks semester filter despite stakeholder emphasis on semester-specific data
  4. Weighted distribution algorithm underspecified — current rules-based system doesn't clearly expose how the weight/fair-split logic is configured or visualized

Assignment criteria complexity:

Top ambiguities:

  1. Weighted distribution: Is it deterministic (capacity only) or does admin tune weights? How is it shown to admin?
  2. Per-TA specialization UI: Where/how does admin set "TA X handles Level 1–2 only" or "TA Y for new students only"?
  3. Live session metrics: Are these derived from appointments + schedules, or entered separately? How are "slots" distinct from "sessions"?
  4. Average grade computation: Which submissions/grades are included? All-time or this-semester?
  5. Semester context in Assignment Criteria: Is there a semester selector, or is it implied from global context (e.g., Semester Hub entry point)?