ADR-001 — Close Workflow → End Checklist
ADR-001: Close Workflow → End Checklist
Status: Accepted | Date: 2026-04-15 | Supersedes: v1 spec 04-semester-management.md §3.8
Context — What v1 does and why
The v1 spec defines a 5-step gated Close Workflow (§3.8) as a tab on the Semester Hub. Steps: (1) Review EOC Assessments, (2) Confirm Promotions, (3) Bulk Payment Setup, (4) Handle Leavers, (5) Verify. Each step must complete before the next unlocks. The Step 2→3 gate was specifically designed to prevent documented workaround W4 — payment setup before promotions finalized. Gate overrides require admin reason + logging.
The v1 workflow scored WF3 improvements from 8+ screens / 40-70 clicks / 3 external tools down to 4-6 screens / 15-25 clicks / 0 external tools (00-spec-index.md §10).
Decision — What was decided
Replace the 5-step gated Close Workflow with a flat End Checklist tab, structurally parallel to the existing Setup Checklist (§3.6). Gated steps become automated backend triggers. Stakeholder to define "automatic" per step.
Rationale — Stakeholder reasoning (from meeting)
- "I'm not too convinced of all these steps that are being proposed." — gated workflow too rigid for 1-3 power users.
- "Review EOC assessments. So this could be. Automatic." — EOC review should auto-close based on submission deadline.
- "Confirming promotions is. We're doing things manually. And I'm hoping we don't do things manually anymore." — promotions should be automatic.
- Kamran summary: "we'll remove the gated workflow for 4.3 and then do a checklist and then you're gonna have to define what automatic means."
Consequences
First-order — direct spec changes
- 04-semester-management.md §3.8: complete rewrite. Remove 5-step stepper, gate logic, gate overrides, inline documentation block, per-step data tables/actions/states, and Close Workflow States. Replace with flat End Checklist following §3.6 (Setup Checklist) patterns — checklist items with status badges, progress bar, no ordering gates.
- 04-semester-management.md §8 (Cross-Domain Integration): rewrite §8.1, §8.2, §8.6 to reference End Checklist instead of Close Workflow steps.
Second-order — cascade to OTHER specs (list every file + section)
| File | Refs | Sections to update |
|---|---|---|
| 00-spec-index.md | 7 | §3 nav tree (tab name), §5 new screens inventory (Semester Hub description), §6 WF3 workflow (screen sequence + metrics), §8 glossary ("Close Workflow" entry) |
| 01-global-patterns.md | 2 | §4.3 status colors ("close workflow steps" context on Pending badge), §6.3 inline docs example text |
| 02-dashboard.md | 6 | §2.2 phase prompt tile (Close phase text "Step X of 5"), §3.3 progress details (close workflow step progress), §3.4 click targets, §3.5 data sources, §6 data dependencies table |
| 03-student-management.md | 2 | §5 Promoted Students entry points ("Close Workflow > Step 2" link), §5.4 empty state text |
| 08-billing-payments.md | 2 | §2 Payment Overview workaround table (W7 → Close Workflow Step 3), §8.3 cross-domain integration ("Close Workflow Step 3" heading + content) |
What we lose — v1 benefits accepted as trade-off
- W4 mitigation: the Step 2→3 gate (§3.8, line 494) explicitly prevented payment setup before promotions finalized. With a flat checklist, nothing enforces ordering. Risk is accepted on the assumption that automatic promotion removes the manual timing dependency.
- WF3 metrics: the claimed 38-50% screen reduction and 55-64% click reduction (00-spec-index.md §10) were measured against the gated workflow. A flat checklist with backend automation may achieve similar or better numbers, but the v1 metrics are no longer valid as stated.
- Audit trail: gate override logging (admin name, reason, timestamp to Reporting > Logs) disappears. No equivalent in a flat checklist.
What we gain
- Simpler mental model — checklist items are independently verifiable, not sequentially locked.
- Backend automation reduces manual steps to near-zero for routine semesters.
- Structural consistency — End Checklist mirrors Setup Checklist, reducing UI patterns to learn.
Implementation notes — what v2 spec should contain; mockup vs production
- v2 spec: define End Checklist default items (TBD — stakeholder deferred), status computation per item, "automatic" trigger definitions per item. Reuse §3.6 component patterns (progress bar, status badges, deep links, "Mark as N/A").
- Mockup: static End Checklist with placeholder items and completion states. No backend triggers — same mock-only approach as Setup Checklist.
- Production: backend must implement automatic triggers before removing gates. If automation is not ready at launch, the flat checklist without gates AND without automation is strictly worse than v1.
Open questions
- What are the default End Checklist items? (Stakeholder deferred: "need to be discussed.")
- Per item: what constitutes "complete"? Which are fully automatic 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)?
- How is the W4 risk (payment before promotion) handled if backend automation is delayed?