Spec — User Notification Preferences

Size: Small–Medium (half to one day of work) Readiness: CONDITIONAL — 2 open questions blocking implementation

Problem Definition

Users currently receive all platform notifications with no ability to control frequency, channel, or type. This creates alert fatigue, causes users to disable notifications entirely, and results in missed high-priority events. Users need a self-service preference center where they can configure what they hear about and how.

Users

Primary: Authenticated end-users managing their own accounts Secondary: Workspace admins who may set notification defaults or enforce org-wide policies

Inputs

• User's current notification preferences (read from user_preferences store)
• Available notification types (sourced from a registry — see Open Question #1)
• Supported delivery channels: in-app, email (SMS not in scope — see Non-Goals)
• Admin-configured policy constraints (e.g., mandatory security alerts cannot be disabled)

Outputs

• Updated preference record persisted to user_preferences
• Confirmation message shown inline after save
• Audit log entry: who changed what, and when

Constraints

• Changes must take effect within one platform event cycle (no lag longer than ~30 seconds)
• Admin-enforced preferences must be visibly locked in the UI — user sees them but cannot toggle them
• Preference reads must not add more than 50ms to page load (cached reads expected)
• No email or push sending logic lives in this feature — this is preference storage only

Non-Goals

• SMS / push notification channels
• Notification scheduling ("only notify me between 9am–5pm")
• Per-item muting (e.g., muting a single document vs. a category)
• Admin ability to blast-override individual user preferences
• Digest / batching configuration

Success Criteria

• A user can change a preference and the next qualifying notification respects that change within 30 seconds
• Locked admin preferences render as read-only with visible explanation text; no silent enforcement
• Preference save completes in under 400ms at p95 under normal load
• Zero preference changes are lost under concurrent save (last-write-wins with optimistic locking is acceptable if documented)
• Audit log entry is present for every preference mutation — verified by integration test

Open Questions

| # | Question | Owner | Blocker? | |---|----------|-------|----------| | 1 | Is the notification type registry static (hardcoded list) or dynamic (fetched at runtime)? Dynamic requires a loading state and error handling path that static does not. | Backend lead | Yes | | 2 | Can workspace admins set default preferences for new users, or only enforce mandatory ones? Defaults = pre-population logic; enforcement = lock UI. These are meaningfully different builds. | Product | Yes |

Completeness Scorecard

| Section | Status | Notes | |---------|--------|-------| | Problem definition | ✅ Complete | | | Users | ✅ Complete | | | Inputs | ⚠️ Partial | Notification type source unresolved (OQ #1) | | Outputs | ✅ Complete | | | Constraints | ✅ Complete | | | Non-goals | ✅ Complete | | | Success criteria | ✅ Complete | | | Open questions | ⚠️ Partial | 2 blocking questions unanswered |

Readiness Score: 6 / 8 sections fully resolved

Verdict: CONDITIONAL ⚠️

Implementation must not begin until Open Questions #1 and #2 are answered. Both affect scope and component structure. Answering them requires no additional research — only a 30-minute product and backend sync.

Once resolved, update the Inputs section and Admin behavior under Constraints, then re-score.

Reviewer Checklist

Before approving this spec for implementation, confirm:

• [ ] OQ #1 resolved: registry type documented and input section updated accordingly
• [ ] OQ #2 resolved: admin capability (defaults vs. enforcement) reflected in Inputs and Constraints
• [ ] Success criteria are testable as written — no criterion reads as "it works"
• [ ] Non-goals have been acknowledged by product (no scope creep items hiding in them)
• [ ] Locked-preference UX has a design reference or explicit owner before build starts
• [ ] Audit log format agreed upon with the team receiving those logs