Skip to content

PPP Pulse — Evening Sleep Recommendation: Notification Timing ​

Status: Draft for Matt's review · Tracking: #6449, #6430 · Spec: docs/features/wellness.md (wellness.notifications.shift-aware-prompt)

Why this document exists ​

The May 12 Dev Session agreed that the evening Sleep Recommendation prompt must be shift-agnostic: a fixed 6pm trigger is meaningless for a doctor who finishes at 22:00, and a 21:00 hard fallback fires during a night shift that started at 20:00. Matt asked Rob to nail down the specific thresholds before further work. This page is that proposal — every number is cited to a peer-reviewed paper or a UK/AUS regulatory body, so the choices survive clinical scrutiny.

TL;DR — proposed values (awaiting Matt's sign-off) ​

ParameterCurrent codeProposedWhy
Awake-threshold to trigger evening prompt (N)12 h14 h3 h buffer before the 17 h cognitive-impairment line
Hard fallback21:00 local clock16 h awake (no clock ceiling)Clock ceilings break night shifts; 16 h matches Dawson & Reid + ACGME
Outside-shift detectiontimesheet AND geofenceunchangedBoth signals already correct; belt-and-braces
Morning-wake detectioninput only (no resolver)wearable sleep_end → morning-draw timestampWearable-first; no phone-unlock (notification fatigue + privacy)
User timezonehard-coded Europe/Londonderive from user's most recent timesheet hospitalRequires hospitals.timezone IANA column (new schema field)

Pseudocode of the revised evaluator:

fire if (awake_hours >= 16)                       # biological hard ceiling
fire if (not on_shift) and (not in_geofence) and (awake_hours >= 14)
otherwise: do not fire

No clock-time appears in the evaluator. The 21:00 wall-clock ceiling is removed entirely — it is what breaks night-shift workers.


Decisions needed from Matt ​

For each question below, the recommended option is bolded.

Decision 1 — Awake threshold N ​

How many hours after wake should the evening prompt fire (assuming the doctor is off-shift and outside the hospital geofence)?

  • A. 12 h (current code default) — fires very early; risks notification fatigue
  • B. 14 h — Recommended. 3 h before the 17 h impairment line; lets the doctor act on the prompt before cognition degrades
  • C. 16 h — Matches Dawson & Reid line exactly; fewer notifications but no buffer to act

Source: Dawson & Reid 1997 (Nature), Williamson & Feyer 2000 — 17 h awake ≈ 0.05% BAC cognitive equivalency.

Decision 2 — Hard ceiling: clock-time or hours-awake? ​

The current code has HARD_CEILING_HOUR_LOCAL = 21 — fire at 21:00 local regardless of shift/geofence/awake. This breaks night-shift workers — the prompt fires while they are mid-shift at 21:00.

  • A. Replace clock ceiling with awake-hours ceiling: 16 h. Recommended. Biologically grounded, shift-agnostic, works for any rotation pattern.
  • B. Keep 21:00 ceiling but suppress it when onActiveShift — defensive, but adds complexity and still fires too early for late-evening shifts
  • C. Drop the ceiling entirely, rely only on the 14 h trigger — risk: if geofence data missing AND user never logs out of shift, no prompt fires

Decision 3 — Timezone source ​

The user's "local hour" question becomes irrelevant if Decision 2 picks the hours-awake ceiling. But timezone still matters for the morning-draw scheduler and Workload Recommendation prompt. Current code uses a hard-coded Europe/London.

  • A. Derive from user's most recent timesheet hospital → fall back to instance_config.timezone if no timesheet. Recommended. Requires a one-line schema change: add hospitals.timezone varchar(64) IANA field. Backfill: UK hospitals → Europe/London; AU hospitals → derive from state.
  • B. User self-selects timezone in profile — extra UX, easy to forget to update
  • C. Derive from device locale on each app open — works but flakes when doctor travels for conferences

Decision 4 — Morning-wake detection source ​

Today the evaluator takes awakeSince as an input but has no resolver. This decision defines the resolver.

  • A. Wearable sleep_end (Garmin/Apple Health/Oura/Whoop/Fitbit) → morning-draw timestamp (existing daily compute) → no prompt if neither. Recommended. Wearable-first, graceful fallback, no phone-unlock signal.
  • B. First phone unlock after midnight — rejected. Doctors check phones overnight; signal is too noisy. Privacy implications (continuous unlock monitoring).
  • C. First app open after a 6 h+ gap — possible v2 fallback if many users lack wearables, but morning-draw timestamp covers most of this already.

Decision 5 — Out-of-scope items (confirm) ​

  • Manual "end shift" trigger — Matt's option (3) on the original issue. Proposal: out of v1. No evidence base; adds UX friction; timesheet start/end already provides this signal. Revisit if ≥3 users explicitly ask for it post-launch.
  • Clinical supervisor notification — already explicitly on hold per #6449. No change.

Evidence base ​

This research was conducted via Gemini deep research on 2026-05-20 (68 sources across WHO, ILO, UK BMA/GMC/RCS, AUS RACS/AHPRA/AMA, US ACGME, peer-reviewed sleep science, and consumer wearable platforms).

Universal biological thresholds (jurisdiction-independent) ​

ThresholdValueSource
Awake → 0.05% BAC cognitive equivalent17 hDawson & Reid, Nature 1997; Williamson & Feyer, Occup Environ Med 2000
Awake → 0.10% BAC cognitive equivalent24 hDawson & Reid 1997
Linear cognitive decay rate (hours 10–26 awake)~0.74% / hDawson & Reid 1997
Recommended adult sleep duration7–9 hAASM/SRS consensus 2015; NSF 2015
Strategic nap15–30 min (under 30 to avoid sleep inertia)WHO; CDC/NIOSH

These numbers do not vary by country, employer, or training stage. They are the bedrock for any clinical-grade fatigue intervention.

UK regulatory thresholds (BMA Fatigue & Facilities Charter 2024) ​

  • Max 4 long shifts in a row, max 7 consecutive shifts of any length
  • Max 72 h in any 168 h (7-day) window
  • Minimum 46 h recovery after final night shift
  • 30-min paid break for shifts >5 h; second 30-min break for shifts >9 h

UK Royal College of Surgeons (Safe Shift) ​

  • Shifts no longer than 12–13 h
  • 7 consecutive 13-h night shifts "strongly discouraged"
  • After night shifts: 2 uninterrupted nights' sleep before returning to days

Australian regulatory thresholds (RACS Standards for Safe Working Hours) ​

  • Daytime: ≤70 h/week averaged over 4 weeks
  • Nighttime: ≤60 h/week averaged over 4 weeks
  • ≥2 sequential full days off in each 14-day cycle
  • No elective surgical list >12 h; no routine hours after 22:00
  • ≥1 h handover overlap between shifts

WHO / ILO international baselines ​

  • Max shift: 12 h
  • Min inter-shift rest: 11 h
  • Max weekly hours: 48 (EWTD/WTR baseline; UK applies to junior doctors)
  • Night work defined as ≥7 consecutive hours including midnight–05:00
  • 24 h continuous weekly rest

US ACGME (outlier, for context only) ​

  • 80 h/week averaged over 4 weeks
  • Max 24 h continuous duty + 4 h handover
  • 8 h minimum rest between scheduled duties (10 h preferred)
  • 14 h post-call rest after 24 h in-house call
  • ACGME explicitly suggests strategic napping after 16 h continuous duty between 22:00–08:00. This 16-h figure independently validates Decision 2.

Digital health precedent ​

PlatformNotification triggerNotes for PPP
Apple Health Wind DownUser-defined 15 min – 3 h before bedEstablishes that wind-down windows are subjective
OuraExactly 1 h before algorithmic bedtimeExplicitly criticised for breaking on shift workers — assumes static circadian rhythm, pings at 21:00 mid-night-shift. Strong negative precedent — PPP must not replicate.
WhoopAdaptive Sleep Need from accumulated strainNo hardcoded wind-down; community converges on 30–60 min routine
GarminManual bedtime + Evening ReportConservative; avoids aggressive pings

Behavioural-science synthesis (LSE, NIH digital-health literature): static clock-time triggers fail shift workers; dynamic, roster-aware, awake-duration-based triggers are the established best practice. The PPP Pulse architecture (timesheet + geofence + awake-duration) is already aligned with this consensus — the change proposed here completes the alignment by removing the last clock-time element (the 21:00 ceiling).


Worked examples ​

To pressure-test the proposed values against real shift patterns.

Example A — day-shift consultant, 08:00–18:00 ​

  • Wakes 06:00 (wearable sleep_end = 06:00)
  • Shift ends 18:00, leaves geofence 18:30, home 19:00
  • 14 h awake reached at 20:00 → prompt fires 20:00 (off-shift ✓, outside geofence ✓, awake ≥14 h ✓)
  • Hard ceiling (16 h = 22:00) never engages

Example B — night-shift registrar, 20:00–08:00 ​

  • Wakes 16:00 (afternoon sleep, wearable sleep_end = 16:00)
  • 14 h awake reached at 06:00 — but still on shift, so does not fire
  • Shift ends 08:00, leaves geofence 08:30
  • At 08:30: awake 16.5 h, off-shift, outside geofence → prompt fires 08:30 (the doctor's "evening" wind-down)
  • Hard ceiling triggers at 08:00 (16 h since 16:00 wake) — would fire even if still on shift, which is correct: 16 h awake is biologically dangerous regardless of whether the shift has technically ended

Example C — split-shift / long elective list, 09:00–22:00 ​

  • Wakes 07:00 (wearable sleep_end = 07:00)
  • Shift ends 22:00, home 23:00
  • 14 h awake reached at 21:00, still on shift → does not fire
  • 16 h awake reached at 23:00, off-shift, outside geofence → prompt fires 23:00
  • Note: under the current 21:00 clock ceiling, this doctor would have received the prompt at 21:00 while still operating — exactly the kind of notification fatigue we want to avoid

Example D — wearable not connected, no morning-draw run yet ​

  • wearable.sleep_end = null, morning_draw_timestamp = null
  • awakeSince = null → awakeHours = null
  • 14 h trigger: not met (null < 14)
  • 16 h ceiling: not met (null < 16)
  • → no prompt fires. Acceptable: better to miss one day than fire an uncalibrated prompt. Morning-draw will populate within 24 h for any user who opens the app.

Implementation impact ​

Code changes (small) ​

api/backend-ppp/src/services/wellnessService/readiness/eveningDrawTrigger/eveningDrawTriggerService.ts:

diff
- export const DEFAULT_AWAKE_THRESHOLD_HOURS = 12;
+ export const DEFAULT_AWAKE_THRESHOLD_HOURS = 14;

- export const HARD_CEILING_HOUR_LOCAL = 21;
+ export const HARD_CEILING_AWAKE_HOURS = 16;

The getLocalHour helper and timeZone input become unused inside the evening evaluator. They remain in the schema for the morning draw scheduler, which still needs the user's timezone to dispatch jobs sensibly.

Schema change (new — one column) ​

packages-shared/ppp/src/schema-groups/hospitals.ts:

diff
  country: varchar('country', { length: 100 }).notNull(),
+ timezone: varchar('timezone', { length: 64 }), // IANA tz id

Backfill in drizzle/NNNN_hospitals_timezone.sql:

sql
UPDATE hospitals SET timezone = 'Europe/London' WHERE country = 'United Kingdom';
UPDATE hospitals SET timezone = 'Australia/Sydney'    WHERE country = 'Australia' AND state IN ('NSW','VIC','TAS','ACT');
UPDATE hospitals SET timezone = 'Australia/Brisbane'  WHERE country = 'Australia' AND state = 'QLD';
UPDATE hospitals SET timezone = 'Australia/Adelaide'  WHERE country = 'Australia' AND state IN ('SA','NT');
UPDATE hospitals SET timezone = 'Australia/Perth'     WHERE country = 'Australia' AND state = 'WA';

Resolver added to wellnessService/util/userTimezone.ts (new file): most-recent timesheet's hospital → fall back to instance_config.timezone.

Tests ​

eveningDrawTriggerService.test.ts adds cases for examples A–D above.

Spec / Changelog ​

  • docs/features/wellness.md AC wellness.notifications.shift-aware-prompt flipped from ⏳ to ✅ once Matt signs off
  • docs/features/.changelog/wellness/2026-05-20-prNNNN.md fragment with the rationale and a link back to this document

Sources ​

Full citation list from the Gemini deep research (2026-05-20, 68 sources):

  1. Dawson, D., Reid, K. (1997). Fatigue, alcohol and performance impairment. Nature 388, 235.
  2. Williamson, A.M., Feyer, A.-M. (2000). Moderate sleep deprivation produces impairments in cognitive and motor performance equivalent to legally prescribed levels of alcohol intoxication. Occup Environ Med 57, 649–655.
  3. AASM & Sleep Research Society (2015). Recommended Amount of Sleep for a Healthy Adult: A Joint Consensus Statement. Sleep 38(6) and J Clin Sleep Med 11(6).
  4. National Sleep Foundation (2015). Sleep Duration Recommendations. Sleep Health 1(1), 40–43.
  5. BMA Fatigue and Facilities Charter (updated 2024). https://www.bma.org.uk
  6. General Medical Council — Caring for Doctors, Caring for Patients. https://www.gmc-uk.org
  7. Royal College of Surgeons of England — Safe Shift guidance. https://www.rcseng.ac.uk
  8. Royal Australasian College of Surgeons — Standards for Safe Working Hours and Conditions. https://www.surgeons.org
  9. WHO / European Commission — Healthcare worker shift recommendations.
  10. ILO Conventions No. 1 (1919), No. 14 (1921), No. 30 (1930), No. 106 (1957), No. 171 (1990). https://www.ilo.org
  11. ACGME Common Program Requirements (Resident Duty Hours, 2003/2011/2017 revisions). https://www.acgme.org
  12. AHPRA Code of Conduct / mandatory notification framework. https://www.ahpra.gov.au
  13. AMA Safe Hours Audits — Australian Medical Association. https://www.ama.com.au
  14. CDC / NIOSH — Strategic napping guidance for shift workers.
  15. Apple Health Wind Down / Sleep Focus documentation. https://support.apple.com
  16. Oura Ring — Bedtime guidance algorithm; community feedback on shift-work failure mode.
  17. Whoop — Sleep Planner / Sleep Need methodology. https://www.whoop.com
  18. Garmin — Sleep Coach / Body Battery documentation. https://www.garmin.com
  19. LSE / NIH — Behavioural science on digital health notification adherence.

Full research transcript with all 68 grounded source links is preserved at /home/rob/.config/gemini-mcp/output/38204711eda49b95/deep-research-2026-05-20T10-48-08-593Z.json for audit.


Author: Rob Duncan (with Gemini deep research) — 2026-05-20. Open to revision via PR.

Internal documentation — org members only