ADR-002 — Assignment Criteria Hybrid Matrix

ADR-002: Assignment Criteria → Hybrid Per-TA Matrix

Status: Accepted | Date: 2026-04-15 | Supersedes: v1 spec 07-teacher-management.md §4

Context — What v1 does and why

V1 §4 defines a generic rules engine for auto-assigning students to TAs. Admins CRUD prioritized rules from a catalog of four types: Gender Match, Timezone Proximity, Level Specialization, and Capacity (§4.3). A separate system-level toggle auto-assigns repeat students to their previous TA before other rules fire (§4.4). The rules engine scored 30/35 in the WS1.5 evaluation for its flexibility to express arbitrary constraint combinations.

The problem: nobody configures assignment that way. The stakeholder configures per-TA — "which TAs handle which levels," "max capacity for each TA," "who takes new vs. returning students" — not abstract rules applied globally.

Decision — What was decided

Replace the rules engine with a hybrid per-TA matrix as the primary configuration surface:

1. Per-TA matrix (new): Each TA row exposes capacity (max students this semester), level specialization (checkboxes), and new-vs-returning routing.
2. Named rules (preserved, reduced): Gender match (automatic), repeat-student auto-assign (toggle, per v1 §4.4), distribution strategy (weighted by capacity percentage).
3. Read-only preview: "If N students enroll, current config assigns: TA A: X, TA B: Y" — shows the weighted distribution outcome.
4. Timezone proximity rule: Dropped. Stakeholder explicitly rejected ("no no").

Rationale — Stakeholder reasoning (from meeting)

The stakeholder described weighted distribution by example: "the one that can only take 10 students takes one student and the one that can take 100 takes maybe five students. Because you want to give a bigger workload to the person who can take much more because it's based on percentage." This is deterministic from capacity — not a tunable weight, but a proportional fill algorithm. The per-TA matrix makes each TA's constraints directly visible and editable rather than hiding them inside abstract rule definitions.

Consequences

First-order — direct spec changes

• V1 §4.3 (generic rule CRUD) replaced with per-TA matrix UI
• V1 §4.4 (repeat-student toggle) preserved as a named rule
• V1 §4.1-4.2 (purpose, entry points) updated to reflect matrix surface
• Semester Hub Setup Checklist link (§4.2) still valid — points to same screen, different UI

Second-order — cascade to OTHER specs

• 04-semester-management: Setup Checklist item description changes ("Configure assignment matrix" vs. "Configure assignment rules")
• 02-dashboard: no change — no dashboard tiles reference assignment criteria internals
• Mock data (src/data/): replace rules array with per-TA config records

What we lose — v1 benefits accepted as trade-off

• Arbitrary rule composition: v1 could express any future constraint as a new rule type. The matrix is fixed to three axes (capacity, level, student-type). Adding a new axis requires schema change, not just a new rule row.
• Priority ordering flexibility: Rules had explicit priority integers. The hybrid model has implicit precedence (gender match → repeat-student → matrix constraints → weighted fill).
• Timezone rule: Removed entirely. If needed later, it would require adding a column to the matrix or reintroducing a rules mechanism.

What we gain

• Direct alignment with how the stakeholder actually configures assignments today
• Per-TA visibility — admin sees each TA's full constraint profile in one table
• Weighted distribution preview makes the algorithm's output transparent before enrollment
• Reduced cognitive overhead: three configuration axes vs. an open-ended rule builder

Implementation notes — what v2 spec should contain; mockup vs production

V2 spec should define: matrix column schema (TA name, capacity, levels[], student-type, active), named rules section (gender-match auto, repeat-student toggle, distribution strategy selector), preview panel layout.

Mockup: Static matrix table with mock TA rows, toggle controls for named rules, static preview panel showing example distribution. No algorithm computation — hardcoded preview numbers.

Production: Weighted fill algorithm (proportional to remaining capacity), conflict resolution when constraints cannot all be satisfied (flag unassignable students for manual placement), semester-scoped config records.

Open questions

1. Weighted distribution: Deterministic from capacity (stakeholder's example implies yes) or admin-adjustable weights? Default to deterministic; confirm with stakeholder.
2. Conflict resolution: When no TA matches all constraints (e.g., no female TA handles Level 3 for new students), what is the fallback? Manual assignment queue?
3. Semester binding: Is the Semester Hub entry point sufficient context, or does the screen need an explicit semester selector?

Amendments

2026-04-22 — Repeat-Student Auto-Assign rule inverted

Source: QF-Backend-Review-Apr-22.md lines 121–125. Canonical record: STAKEHOLDER-ANSWERS-2026-04-22.md §C.

What changes: The Repeat-Student Auto-Assign rule (§4.4.2 in 07-teacher-management.md, Decision item 2 above) is inverted. The v1 policy — "auto-assign repeat students to their previous TA" — was a misread of the actual stakeholder policy.

Superseded wording (preserved here as history, now stale):

"Repeat students should be auto-assigned to their previous teacher." (This was quoted as an "Addresses interview request" note in v1 §4.4 and carried forward verbatim into v2 §4.4.2.)

New wording (Apr 22, verbatim):

"For repeat students, we will assign them to a different teacher, if at all possible. So that's like our policy and that kind of goes into like assignment criteria as well. That a student, if possible, is assigned to a different teacher for the upcoming semester." — Lejla, Apr 22 transcript L125.

New behavior:

1. On re-enrollment of a repeat student, the assignment engine attempts to place them with a TA they have not had previously — with gender-match and capacity constraints still applied.
2. If no eligible alternative TA exists (all other matched TAs are at capacity, gender-mismatched, or inactive), fall back to the previous TA.
3. If even the previous TA is unavailable, fall through to standard matrix distribution.
4. Rule label in UI: "Repeat-Student Rotation" (replaces "Repeat-Student Auto-Assign"). Default: on.

Consequences:

• First-order: 07-teacher-management.md §4.4.2 text + label + default-on description updated.
• Second-order: mock copy in src/data/admin-notes.ts that reads "Continuity preserved via repeat-student auto-assign rule" becomes stale and must be updated in the mockup pass (flagged in _apr22-worklog.md, not in this spec pass).
• Third-order: preview-panel distribution projection math is unaffected (rotation rule fires before matrix phase, same as before).

What we explicitly preserve:

• The v1 source quote above, so future readers can trace the inversion back to its origin.
• The named-rule structure (still one toggle in the Named Rules panel).
• Precedence position (evaluated after gender match, before matrix distribution).