Covert requirements to feature specs

docs/features/notifications.md

@@ -0,0 +1,73 @@
+# Feature: Notifications
+
+**Source:** VSMS Functional Requirements v1.1, Section 5
+
+---
+
+## Delivery
+
+- **Email is required** for all notifications in MVP.
+- SMS is nice-to-have for a future release.
+- All Admin notifications are email only.
+
+---
+
+## Monthly Schedule Publish
+
+| FR ID | Requirement | Notes |
+|-------|-------------|-------|
+| **FR-N01** | When Admin publishes a month's schedule, each assigned volunteer receives **a single email** listing all their shifts for that month. | One email per volunteer, not one per shift. |
+| **FR-N02** | The monthly email includes a single **'I've seen my schedule'** acknowledgement button. Clicking it marks the volunteer as acknowledged for that entire month. The email instructs: if they cannot make any shift, they must log in and book time off. | Acknowledgement covers the whole month — not per-shift. |
+| **FR-N03** | Admin can see acknowledged vs. unacknowledged status per volunteer on the schedule view. Unacknowledged volunteers are visually flagged. | |
+
+> **✦ Nice to Have (post-MVP):** If a volunteer has not acknowledged within 3 days of the monthly publish email, the system automatically sends them a reminder.
+
+---
+
+## Open Decisions
+
+- **Default acknowledgement state:** If a volunteer never responds to the monthly email, are their shifts treated as acknowledged or unacknowledged? *(⚠ Open Decision)*
+- **Time-off link in monthly email:** Should the email include a direct link to the time-off page for volunteers who know they cannot attend a shift? *(⚠ Open Decision)*
+
+---
+
+## Shift Reminders
+
+| FR ID | Requirement | Notes |
+|-------|-------------|-------|
+| **FR-N04** | **24 hours** and **1 hour** before each shift, all assigned volunteers receive a reminder notification. | |
+| **FR-N05** | The 24-hour reminder includes two actions: **'I'll be there'** and **'Cannot Attend'**. | |
+| **FR-N06** | If a volunteer clicks 'Cannot Attend', they must select a mandatory reason before submitting. | Options: Sick, Emergency, Work conflict, Other (free text) |
+| **FR-N07** | On 'Cannot Attend': the shift spot is marked open, the cancellation reason is recorded, and Admin is notified immediately. | |
+
+---
+
+## Other Volunteer Notifications
+
+| FR ID | Requirement | Notes |
+|-------|-------------|-------|
+| **FR-N08** | When a published shift is edited (assignments or capacity changed), all volunteers assigned to that shift are notified and their acknowledgement status is reset. | |
+| **FR-N09** | When a volunteer is added to a shift mid-month (after publishing), they receive a notification about the newly added shift. | |
+| **FR-N10** | When a published month is retracted (unpublished), all assigned volunteers are notified. | |
+
+---
+
+## Admin Notifications
+
+Each Admin can configure which of the following they receive. All delivered by email, individually per event.
+
+| FR ID | Event | Content |
+|-------|-------|---------|
+| **FR-N11** | Volunteer clicks 'Cannot Attend' | Volunteer name, shift details, reason provided |
+| **FR-N12** | Volunteer submits time off | Volunteer name, dates, optional reason |
+| **FR-N13** | Volunteer claims an open shift | — |
+| **FR-N14** | Shift drops below minimum volunteer capacity | One alert per threshold breach |
+| **FR-N15** | Trainee becomes eligible for promotion (2 shifts completed) | Informational only — promotion is always a manual action |
+
+> **TBD:** Admin notification configurability — whether this is a simple toggle list or something more complex depends on implementation effort.
+
+---
+
+## Open Decisions
+
+- **Understaffing alert timing:** How many days before a shift should Admin be alerted if it is still below minimum capacity? Admin-configurable — default value TBD. *(⚠ Open Decision)*