Technical Specification — RecoveryDeck (iOS)

Companion: PRD.md · REVIEW_NOTES_RESPONSE.md Product name: RecoveryDeck Version: 1.3 Date: 2026-08-02 Status: Draft for approval (no implementation until approved) Changelog 1.2: Rename RecoveryDeck; local analytics; 1–7 questionnaire + habits; displayName; export schema. Changelog 1.3: Baselines Couzens-style 7d vs 60d ±1 SD; caffeine time/amount + last meal fields; short orthostatic kept.

1. Overview

Native iOS application (Swift + SwiftUI) that:

1. Enforces a per-local-day questionnaire gate
2. Streams Polar H10 BLE heart rate / RR intervals
3. Computes rMSSD (Elite HRV replacement)
4. Runs a guided orthostatic protocol
5. Persists all data on-device only

Target: personal sideload / TestFlight to owner. Architecture must not preclude App Store later.

2. Platform and project setup

2.1 Xcode project layout (suggested)

RecoveryDeck/
  App/
    RecoveryDeckApp.swift
  Features/
    Onboarding/
    Questionnaire/
    Today/
    MorningMeasurement/   # combined rMSSD + orthostatic session
    History/
    Settings/
  Services/
    Bluetooth/
      HeartRateClient.swift
      PolarH10Identifiers.swift
    Metrics/
      RMSSDCalculator.swift
      OrthostaticCalculator.swift
      BaselineCalculator.swift
    Persistence/
      Models.swift
      DayRepository.swift
    Notifications/
      NotificationScheduler.swift
  Resources/
    Info.plist keys (BLE usage strings)
  Tests/
    RMSSDCalculatorTests.swift
    OrthostaticCalculatorTests.swift
    BaselineCalculatorTests.swift
    GateLogicTests.swift

3. Permissions and Info.plist

Not used in v3: HealthKit, Motion (unless later for stand detect — out of scope), Background Modes for BLE (sessions are foreground only).

4. Bluetooth / Polar H10

4.1 Services and characteristics

Use standard BLE SIG profiles (H10 supports these):

RR intervals: Parse HR Measurement flags per Bluetooth HR Profile:

• If RR-Interval bit present, extract RR values in 1/1024 s units → convert to ms:

rr_ms = rr_raw * 1000 / 1024

If a firmware/connection path yields HR-only without RR:

• Cannot compute true rMSSD from integer BPM alone.
• UX: error “RR intervals not available — ensure H10 is snug, charged, and not connected exclusively elsewhere; prefer H10 in heart rate mode.”
• Optional degraded mode: store mean HR only; mark rmssd null — do not fake rMSSD from BPM.

4.2 Connection UX

1. User taps Connect Polar H10
2. Scan for peripherals advertising HR service (or known Polar name prefix Polar H10)
3. Connect + subscribe to HR Measurement notifications
4. Show live BPM + “RR OK” indicator when RR present
5. On disconnect mid-test: pause, offer Resume/Restart
6. Only one session owns the peripheral at a time

Note: iPhone may already be bonded; handle reconnect. Instruct user to disconnect H10 from other apps (Elite HRV, Polar Beat) during measurement.

4.3 Sample model

struct HRSample: Sendable {
  let timestamp: Date
  let bpm: Double?          // from HR field when present
  let rrIntervalsMs: [Double] // zero or more RR since last notification
}

Feed AsyncStream<HRSample> into session VMs.

5. Metric algorithms

5.1 rMSSD

Definition: Root mean square of successive differences of valid NN (RR) intervals.

For successive valid intervals \(RR_i\), \(RR_{i+1}\) (ms):

\[ rMSSD = \sqrt{ \frac{1}{N-1} \sum_{i=1}^{N-1} (RR_{i+1} - RR_i)^2 } \]

Window (normative): accumulate accepted RR until sum(RR) ≥ 60_000 ms, with min 45 accepted intervals and max wall-clock 90 s after settle; fail quality if either floor not met. (Physiological 60 s of RR, not wall-clock-only.)

Settle: 15.0 s wall-clock after user confirms still; discard RR during settle for rMSSD (may still show live HR).

Artifact rejection (v3, simple and documented):

1. Drop RR < 300 ms or > 2000 ms
2. Drop RR where successive difference > 20% of previous RR (ectopic/motion heuristic)
3. Track artifactRatio = rejected / (accepted+rejected)
4. If artifactRatio > 0.20 or accepted count < 45 → quality fail, prompt retry

Also store: mean RR, mean HR = 60000/meanRR, SDNN optional (not primary UI).

Unit tests: golden vectors of RR lists → known rMSSD (hand-calculated fixtures).

5.2 Mean HR over a phase

For orthostatic lying/standing phases of wall duration T:

• Prefer mean of BPM samples in window, or 60000/mean(RR) if RR dense
• Peak standing HR: max BPM over the full 60 s standing window (includes early rise; Couzens peak response)

5.3 Orthostatic derived

avgLyingHR
avgStandingHR
peakStandingHR
gapAvg  = avgStandingHR - avgLyingHR
gapPeak = peakStandingHR - avgLyingHR

5.4 Baselines and green / yellow / red (Couzens-aligned)

Couzens dashboard approach (Ch.13 materials): 7-day rolling mean (acute) vs 60-day rolling mean (norm), with a normal band ≈ ±1 SD around the long-term mean. Values inside the band look “normal for this athlete”; outside is highlighted.

Per metric series (rMSSD, avgLyingHR, gapPeak, gapAvg, subjectiveMean):

Traffic lights (normative):

Concerning directions (for tips / emphasis, not for ignoring the opposite side):

Absolute subjective fallback if not enough history: mean ≥ 5.0 green-ish, ≥ 3.5 yellow-ish, else red-ish (same polarity as before).

Composite chip (optional): majority of channel lights; ties → yellow. Label “rough signal — not medical.”

Not clinical cutoffs; personal statistical bands after Couzens’ visualization pattern.

6. Session state machines

6.1 Combined morning measurement flow (v3 primary — locked)

Single CTA: Start morning measurement. Matches PRD §6.1 / §6.5.

State: Idle
  → Connecting
  → ConnectedLive (show BPM)
  → User taps Start (must be post-questionnaire)
  → SettleLying (15 s)
  → CaptureRMSSD (accumulate RR ~60 s sum)
  → CaptureLyingHR (30 s wall, mean HR)   // orthostatic lying / daily RHR
  → PromptStand (3 s countdown + haptic)
  → CaptureStanding (60 s wall)
  → Complete (persist MeasurementBundle; overwrite if same localDate confirm)
  → Error/Cancel from any state

Total: 15 + 60 + 30 lying + 3 cue + 60 standing ≈ ~3 min + connect.

Remeasure: If MeasurementRecord exists for localDate, require confirm → overwrite same row (v3: no version history).

6.2 HRV-only path

If orthostatic skipped (PRD O1b):

Settle 15 s → RMSSD 60 s → persist HRV partial → Today shows orthostatic missing

Skip requires confirm: “Skip orthostatic today?”

6.3 Gate logic (pure function — unit test)

func canAccessHistory(today: LocalDate, questionnaire: DayRecord?) -> Bool
func canStartMeasurement(today: LocalDate, questionnaire: DayRecord?) -> Bool

Rules per PRD §6.2.

7. Data model

7.1 SwiftData entities (conceptual)

DayRecord

MeasurementRecord

AppSettings

7.3 Local analytics (on-device only)

Store lightweight events in the same sandbox (separate entity or append-only log), e.g.:

• morning_completed, orthostatic_skipped, hrv_quality_fail, session_duration_ms, ble_connect_fail

No network upload. Surface a simple Settings → Analytics summary. Export may include analytics if user exports “full backup.”

7.4 Future export (v4+ — not implemented)

Stable JSON protocolVersion so a later module can map fields → TrainingPeaks metrics / Intervals wellness without schema thrash.

7.2 Completeness

day.isComplete = questionnaire done && rmssd present && quality ok && (orthostatic ok || skipped).

8. Persistence and privacy

No network client in v3 targets. CI should fail if new URLSession analytics appear.

9. UI specifications (behavioral)

9.1 Questionnaire

• Five required steppers / tappable 1–7 chips (Block A+B)
• Optional Block C: last caffeine time, caffeine amount, last meal time (skippable)
• Optional Block D habit chips + Block E notes
• Large touch targets; submit sticky
• Cannot navigate to History via Tab until required scores submitted

9.2 Session UI

• Large phase title
• Countdown / progress
• Live BPM
• Cancel always available
• Success checkmark → auto-return Today

9.3 Accessibility

• Dynamic Type support for questionnaire
• VoiceOver labels on scores
• Haptics for stand cue (respect reduce motion: visual flash)

9.4 Appearance

• System light/dark
• Calm, minimal; no gamification streaks required in v3 (optional later)

10. Notifications

• UNUserNotificationCenter
• Daily calendar trigger
• ID: morning-checkin-daily
• Reschedule on settings change
• No critical alerts

11. Testing strategy

11.1 Unit tests (required before calling v3 done)

11.2 Manual test checklist (H10)

1. Fresh install → onboarding → notification permission
2. Questionnaire gate blocks History and Start
3. Connect H10; RR indicator green
4. Full combined session completes; values plausible (rMSSD typically tens of ms; not 0; not 500)
5. Kill app mid-session; no corrupt day
6. Skip orthostatic path
7. Second launch same day: questionnaire done; can remeasure with confirm overwrite
8. Next calendar day: gate resets
9. Export JSON non-empty
10. Delete all data

11.3 Parallel Elite HRV (user)

7 days: record both rMSSD; expect similar order of magnitude and co-movement, not equality.

12. Implementation milestones

Estimated effort (solo, familiar with iOS): M0–M1 1–2 days, M2 1–2 days, M3 1–2 days — ~1 week calendar part-time, not a commitment.

13. Error catalog (user-visible)

14. Security notes

• No API keys in repo
• No logging of health samples to third parties
• Debug RR dumps off by default; if enabled, local file only + setting

15. App Store readiness (non-blocking notes)

When/if public:

1. Privacy policy URL
2. App Review notes: Polar H10 required for full function; demo mode with simulator RR fixture for reviewers
3. Simulator demo mode: inject synthetic RR for UI review without hardware
4. Avoid HealthKit until justified
5. Medical disclaimer in App Description

v3 demo mode: compile-flag DEMO_RR for SwiftUI previews and unit-free UI dev without strap.

16. PRD decisions (locked for v3)

17. Explicit non-implementations

• Frequency-domain HRV (LF/HF) — Couzens notes need ~5 min for LF; v3 stays rMSSD + orthostatic
• ECG authentication modes beyond standard HR BLE
• Auto-stand detection via accelerometer
• Cloud sync

18. Acceptance criteria (v3)

1. Questionnaire required before measurements and history.
2. rMSSD computed from H10 RR with documented artifact rules; saved per day.
3. Orthostatic produces lying avg, standing avg, peak, gaps (or skip recorded).
4. Baselines: .building until ≥14 complete days; then G/Y/R vs 60-day ±1 SD band.
5. No network calls in core paths.
6. Export and delete work.
7. Unit tests for calculators and gate pass.
8. Manual H10 checklist completed by owner.

19. References (product science)

• Alan Couzens, readiness composite (HRV, RHR, fatigue, mood, soreness, stress) — training-plan dashboard / Ch.13 materials in local archive
• Alan Couzens, orthostatic 60s+60s, peak vs lying gap — taking-your-understanding-of-hrv.md
• Alan Couzens, HRV alone insufficient; commercial readiness skepticism — distilled monitoring notes
• Bluetooth SIG Heart Rate Profile (RR intervals)

20. Approval

No implementation until PRD + this spec are approved and Zach requests build.

Response to product-review notes (2026-08-02)

Companion to PRD.md / TECH_SPEC.md. Product name going forward: RecoveryDeck.

1. How long should the orthostatic test be? Research vs our protocol

What research / clinical guidelines use

Clinical orthostatic tests are longer because they are optimizing diagnostic sensitivity (POTS, OH), often with BP cuffs, not a 3-minute morning habit with a chest strap.

Our current v3 protocol

~15 s settle + 60 s rMSSD + 30 s lying HR + 60 s stand ≈ 3 min total.

• Aligned with Couzens on the idea (quick daily orthostatic, peak−lying gap).
• Not aligned with clinical 3–10 min stand standards.
• Shorter lying sample (30 s) after rMSSD is a habit tradeoff, not a research gold standard.

Recommendation

Bottom line: Research supports minutes, not seconds, for clinical orthostatic testing. For daily coaching readiness, Couzens-style ~1+1 min is a deliberate lightweight proxy. We should document that honestly and optionally offer a longer stand later—not silently claim clinical equivalence.

2. Evidence behind green / yellow / red signals

Honest answer (current v1.3)

RecoveryDeck no longer uses arbitrary ±10% / ±3 bpm tables as the primary rule.

Couzens’s actual method (dashboard): compare acute (≈7-day) metrics to a long-term norm (≈60-day mean) and shade a normal range ≈ ±1 SD. Outside that band is “not normal for this athlete.” He does not publish a universal green/yellow/red product matrix.

RecoveryDeck G/Y/R (TECH §5.4) implements that idea: green inside ±1 SD, yellow ~1–1.5 SD, red beyond ~1.5 SD, with concerning-direction labels.

What is evidence-backed (directionally)

What is not proven

• That 1.0 / 1.5 SD yellow/red edges are optimal for you (tunable later)
• That a single traffic light predicts adaptation that day

Recommendation

Keep lights as personal-band cues, not medical scores; show direction in words; allow tuning after you have months of data.

3. Analytics: “no SDK” vs in-app analytics

Clarification

Examples of local analytics (stay on phone):

• Days completed / streak
• % mornings with orthostatic skipped
• HRV quality fail rate
• Median time for full session
• Questionnaire item distributions over time

We will update the PRD wording from “no analytics” → “no third-party cloud analytics SDK; first-party local analytics OK.”

4. TrainingPeaks / Intervals.icu sync later

Agreed: not in v3, but optional future (v4+), not a hard forever-no.

Architecture implication (tech): keep DayRecord / MeasurementRecord export-friendly (stable JSON schema) so a later exporter can push:

• Morning metrics as TrainingPeaks “metrics” style fields, or
• Intervals wellness / notes / custom fields

No implementation now.

5. Scale 1–5 vs 1–7

Research (psychometrics, brief)

• 5- and 7-point Likert scales are both widely used and considered adequate.
• 7-point often gives slightly higher reliability / more variance (more discrimination); diminishing returns above ~7–11.
• 5-point is faster and often better for general populations / less fatigue.
• “Weird numbers” (e.g. 1–10, 0–100) help mainly by more resolution, not magic—odd midpoints (5 or 7) give a true center.

Recommendation for RecoveryDeck

Default to 1–7 for core feeling items (athlete daily use, high motivation, want nuance).

Update traffic-light subjective bands when switching (e.g. green mean ≥ 5.0, yellow ≥ 3.5 on 1–7).

6. Questionnaire: Alan + WHOOP-inspired

What Alan actually uses / models (archive)

From Couzens dashboard / readiness materials, morning metrics fed into readiness include:

He emphasizes: multi-input composite; low HRV ≠ ban all easy work; soreness = muscular readiness; life stress often early warning.

WHOOP Journal (what you likely liked)

WHOOP separates:

1. How you feel / recovery-adjacent ratings (mood, etc., product evolves)
2. Behavior tags (yes/no) correlated later with recovery: e.g. alcohol, caffeine, shared bed, meditation, late meals, etc.

The power is habit ↔ recovery association, not a long feelings essay.

Proposed RecoveryDeck questionnaire (v3)

Block A — required (Alan core), scale 1–7 Higher = better for all feeling items (consistent polarity).

1. Fatigue — Exhausted → Fresh
2. Mood — Very low → Great
3. Soreness / heavy legs — Very sore → None
4. Life stress — Very high → Very low

Block B — required short (WHOOP-inspired sleep feel)

1. Sleep quality (subjective) — Terrible → Excellent

(complements Oura; captures “I slept 8h but feel wrecked”)

Block C — optional habit chips (WHOOP-style, yes/no, default off until user enables)

Suggested starter set (user can toggle in Settings later):

• Alcohol last night
• Caffeine after 2pm (or “late caffeine”)
• Hard training yesterday (self-tag)
• Travel / late night
• Illness / sick feel

Block D — optional free text Notes

Gate: Block A + B required before measurements. Block C can be same screen, optional.

7. Name without account

Yes — optional display name in onboarding/Settings.

• Stored only on device
• Used for “Good morning, Zach”
• Not identity verification; no login
• Default: empty → “Good morning”

8. “Friends will break BLE” — what that means

Not “Bluetooth is nonstandard.” BLE HR is exactly what Elite HRV, HRV4Training, Polar Beat use.

It means support reality when people other than you use the app:

Elite HRV has years of edge-case UX and support docs. For you, fine. For App Store friends, expect support load unless troubleshooting is excellent.

9. HealthKit — would it ever make sense?

Recommendation:

• v3: No HealthKit (simpler privacy story, fewer review issues).
• Later (optional):

- Read last-night sleep duration / workouts for context chips - Write optional “mindful session” or a single daily summary only if users want Apple Health graphs

• Avoid writing clinical-sounding “recovery diagnosis.”

10. App name: RecoveryDeck

Approved as product name. Bundle ID suggestion: com.zringstrom.recoverydeck.

Product decisions (updated 2026-08-02 follow-up)

Couzens on green / yellow / red (short)

He does not ship a branded traffic-light product table. He:

• Compares 7-day (acute) metrics to a 60-day norm
• Shades a normal range ≈ ±1 SD (green band in his dashboard figures)
• Flags when the athlete is outside their own range
• Uses “red light” for serious overtraining-type states (e.g. orthostatic Q4), not every off morning

RecoveryDeck’s G/Y/R is an implementation of that normal-band idea, not a quote of Couzens cutoffs.

BLE “friends will break it” (plainer)

Bluetooth itself is fine—Elite HRV uses it too. The hard part is everything around the radio:

Imagine a friend installs RecoveryDeck, wears an H10, and taps Start:

1. Polar Beat is still connected in the background → phone won’t give clean RR to RecoveryDeck → “no HRV.”
2. They didn’t enable Bluetooth permission → blank scan.
3. Strap is loose / dry skin → HR jumps, RR missing → quality fail.
4. They switch to Messages mid-test → app backgrounds → connection drops.
5. They use a generic $30 strap that only sends BPM, not RR → we refuse to invent rMSSD.
6. They’re in a gym full of BLE devices → slow pairing, flaky connect.

You already know “close other apps, wet electrodes, stay in the app.” Friends often don’t—so they think the app is broken when it’s the setup. That’s all “friends will break BLE” meant: support/education, not “BLE is wrong.”

Docs updated in PRD/TECH to reflect the above (see changelog).

RecoveryDeck

Privacy-first iOS morning recovery check-in (personal): forced questionnaire → Polar H10 rMSSD (Elite HRV replacement) → orthostatic test → local history + on-device analytics.

Formerly working title: “Morning Readiness.”

Documents

open docs/index.html

Status

Docs only — not implemented until approved and build is requested.

Hardware

• iPhone
• Polar H10

Privacy

Local-first; optional display name; no third-party cloud analytics SDK; yes first-party on-device analytics.