Wellness algorithm: readiness, sleep & workload
This page explains how the PPP Pulse readiness score and the sleep and workload recommendations are computed, links each piece to the code that runs it, and lets you drag the inputs to see whether the results make sense.
Everything below is traceable to two sources:
- Live code —
api/backend-ppp/src/services/wellnessService/readiness/scoring/formulas.tsandscoreService.ts. - Source model — Matt's spreadsheet "Wellness Algorithm Comm.xlsx" (the design of record, cells referenced inline; opens in Google Drive).
The charts transcribe those formulas into docs/site/.vitepress/theme/components/wellnessFormulas.ts. If the backend changes, that file must be updated to match — keeping the charts honest is the point.
Every chart below is zoomable: hover a chart to reveal the zoom / pan / fullscreen controls (top-right), or hold Ctrl/Cmd and scroll to zoom in and inspect a curve closely.
Sleep recommendation now follows the source model
The sleep recommendation has been reverted to the source spreadsheet's three-input Target Sleep Load model (per Matt, 2026-05-27), replacing the readiness-only formula that had drifted in since the first commit. The readiness-only formula is documented below for historical contrast. One follow-up remains open for Matt: the exact live-sub-score → model-input mapping (OQ-SLEEP-MAP, tracked on #8461). The floor question is resolved: on 2026-06-10 (#8208) the envelope was re-anchored from 7.5–10.5 h to 6–10 h (floor 6, base 6, amplitude 4) so the "Normal" band is reachable. The shaded bands and the 6 h floor line on the sleep charts below show the lowered floor.
1. The readiness score
The PPP Pulse / readiness score is a weighted blend of per-input sub-scores across three groups — Workload (penalties), Recovery (rewards) and Health-vs-baseline — normalised to 0–100. Each input is converted to a 0–1 sub-score by its own curve. Those curves are charted below straight from the live formulas.ts, with the matching spreadsheet cell noted.
timeAtWorkScore() · sheet J4Penalised above ~9.5 h; zero by 13 h.
sleepDurationScore() · sheet J15Live curve differs slightly from the sheet between 6–8 h — flagged on #6161.
hrvScore() · sheet J20Zero below 30 ms; saturates above ~60 ms.
phoneUsageScore() · sheet J11Recovery input — more screen time lowers the score.
cumulativeFatigueScore() · sheet J7/J10Falls as total operating minutes accumulate.
meditationScore() · sheet J18Reaches 1.0 at 15 min, small bonus beyond.
Each curve answers "for this one input, how good or bad is today?" The overall score is the weighted sum of all of them (workload weights are negative penalties, recovery and health are positive). Weights live in the source sheet (column E) and the backend scorer.
2. The sleep recommendation — source model (now live)
The live app uses the source spreadsheet model. Recommended sleep responds to the day's workload and daytime recovery, not the readiness score alone.
Live = Source model (scoreService.ts, calculateSleepGuidanceFromLoad; sheet cells E30–E34) builds a Target Sleep Load from three inputs, then maps it onto a curve:
Sₜ = max(0, Workload × (1 − DaytimeRecovery) × (MorningReadiness below 0.5 ? 1.2 : 1))
hours = max(7, 7 + 3.5 × (1 − e^(−5 × Sₜ)))Former live formula (calculateSleepGuidance, readiness-only — the drift that was reverted; still used only for the evening-draw bedtime ceiling):
hours = clamp(6 + (1 − readiness) × 4, 6, 10)Both label the result with the same bands (cut-offs identical in code and sheet): below 6.5 h Normal, below 8 h Moderate, below 9.5 h Enhanced, otherwise Maximise.
Drag the three inputs. The recommended hours from each model update live, and the chart plots how each responds as one input varies:
Each panel sweeps one input while the other two stay at your slider values, so you can trial use cases and check the numbers make practical sense. The shaded bands are the recovery ranges; the dashed line is the 6 h floor. The solid line is the live (source) model; the faint dashed line is the former readiness-only formula — flat against workload and recovery because it ignored them (the drift reverted in #7670). The floor was lowered to 6 h on #8208, so the "Normal" band is reachable on a light, well-recovered day.
What to look for:
- The former live line is flat when you change workload or daytime recovery — it ignored them entirely. The source line (now live) moves, because sleep need genuinely depends on the day's load and how much you recovered during it.
- The source model floors at the 6 h clinical minimum (lowered from 7.5 h on 2026-06-10, #8208), so the Normal band (computed-hours cut-off below 6.5 h) is reachable on a light, well-recovered day. The former 7.5 h floor had made Normal mathematically unreachable (the resolved OQ-SLEEP-FLOOR on #6161 / #7670 / #8208).
- The card headline and band prompts use Matt's locked display ranges (Normal 7-8 / Moderate 8-9 / Enhanced 9-10 / Maximise 10+), which are distinct from the computed-hours cut-offs above.
- The exact mapping from the live 17 sub-scores onto the model's three inputs is a documented default pending Matt's confirmation — OQ-SLEEP-MAP (#8461).
- Missing data is not zero recovery (#8458): the DaytimeRecovery average runs over only the recovery sub-scores that have underlying data for the day, and a fully absent recovery group reads neutral (0.5). Workload sub-scores keep fail-soft absence semantics — zero input already scores as "no observed load". Before this, a day without wearable data collapsed DaytimeRecovery to 0 and pushed every sparse-data day to Enhanced/Maximise.
3. The workload recommendation
The workload message is keyed off the readiness score alone — no other inputs. As of #8203 (#6161) there are three active bands: High ≥ 75, Moderate 50–74, Low under 50. The top band moved from 85 to 75 because the live algorithm rarely scores into the 90s, so 85 made "full workload OK" hard to attain. A more severe "Poor" band below Low (proposed under 40) is parked for user testing, so under 50 reports Low for now.
The bands are fixed ranges of the readiness score: green is "OK to proceed with full workload", amber is "consider moderating intensity and complex demands", red is "consider reducing demanding tasks and plan more rest".
Provenance
| Piece | Live code | Source cell |
|---|---|---|
| Per-input sub-scores | formulas.ts | column J |
| Overall readiness | scoreService.ts | L27 |
| Sleep recommendation | scoreService.ts calculateSleepGuidanceFromLoad | E30–E34, F34 |
| Workload recommendation | scoreService.ts DEFAULT_GUIDANCE_CONFIG | E38 |
Related: the reconciliation brief and open decisions are tracked on issue #6161.