How it works

What Understory tracks

Understory is a pacing tool that combines objective biometric data (heart rate variability, heart rate) with subjective self-report. It tracks energy expenditure in "spoons," which is community-native vocabulary from spoon theory (Christine Miserandino, 2003), widely adopted in the POTS, ME/CFS, EDS, MCAS, Long COVID, and fibromyalgia communities.

The app surfaces patterns over time. It does not interpret data clinically. It does not provide diagnoses, recommendations, or activity prescriptions. The user controls all data: what is logged, what is shared, and when to delete it. All health data stays on the user's device and personal iCloud by default.

The morning reading

Each morning, the user completes a short guided breathing session on Apple Watch that captures heart rate data. The session lasts 2 to 5 minutes and records beat-to-beat RR intervals. From these intervals, the app computes rMSSD (root mean square of successive differences), a standard short-term heart rate variability metric. If the interval data is incomplete, the app falls back to SDNN (standard deviation of normal-to-normal intervals) from the Watch's own health data store.

The reading always includes a subjective 1-to-10 check-in ("How do you feel this morning?"). The combined score weights 60% biometric and 40% subjective when both data sources are present.

From this data, the app derives a stability score (0 to 100) based on rMSSD plus resting heart rate relative to a personal baseline. The baseline is a 14-day rolling average. During the first 14 days (cold-start period), the app uses absolute thresholds until a personal baseline is established.

Clinical mapping: The stability score reflects autonomic readiness each morning. A provider can ask "What was your stability score this morning?" to gauge capacity for the day.

Heart rate thresholds and passive monitoring

The default exertion threshold is 1.6 times resting heart rate (user-tunable). The multiplier adapts to the individual's actual resting HR rather than using an age-based formula. Users can adjust this value if their provider identifies a different threshold that better fits their condition.

Passive heart rate monitoring uses event-driven observation that wakes the app only when new data arrives, rather than continuous polling. The battery budget is less than 2% extra daily drain, with less than 10% total app overhead. The app does not run an all-day workout session, which preserves battery and avoids interference with other health apps.

Elevation detection triggers when sustained HR exceeds the personal hourly baseline for more than 15 minutes, with a z-score above 2.0 standard deviations. Suppression rules prevent alarm fatigue: no alerts during sleep focus, quiet hours, already-explained sessions, or when rate limiting applies.

Orthostatic detection (POTS feature flag): The app detects HR jumps of 30 or more BPM within 1 minute of a rest-to-standing transition, sustained for 10 or more minutes. These are auto-logged and surfaced in the evening digest.

Clinical mapping: This data can inform conversations about pacing. The app surfaces when the user exceeds their personal threshold without requiring them to watch a monitor continuously.

Spoons as energy budgeting

"Spoons" is community-native vocabulary from spoon theory (Christine Miserandino, 2003). The daily spoon ceiling is personally calibrated during onboarding: no hardcoded ceiling, no hardcoded per-category costs.

Onboarding asks the user about a typical good day, a typical hard day, and activities that feel manageable vs. too much. From these answers the app proposes an initial daily ceiling and per-category costs. Each session's cost factors in a base cost plus an HR multiplier when heart rate data is available.

Adaptive recalibration runs as a nightly background task, analyzing a 30-day rolling window. Changes are small and slow: approximately 0.5 spoons per month of drift under stable conditions. Every calibration change is logged with justification for transparency. The user can also adjust costs manually at any time.

Clinical mapping: The daily ceiling represents what a typical day looks like for this person. Per-category costs describe how much each activity type draws from that total. The app does not enforce the ceiling; it describes where the user stands relative to their typical day. A provider can review spoon patterns to identify which activities consistently exceed the daily total and which categories carry the highest cost.

Post-exertional malaise correlation

When a user logs a PEM event, the app looks back 72 hours. It identifies candidate trigger sessions based on timing, cost, and HR data. The 72-hour window accounts for the documented delayed reaction in ME/CFS and related conditions.

Pattern surfacing occurs only when statistically meaningful: the app requires at least 10 logged PEM events with identifiable correlates before presenting correlation results to the user.

Clinical mapping: Instead of broad avoidance, the user builds a personal evidence base for which activities carry delayed cost. A provider can review these correlations alongside the user to identify patterns and inform planning.

What care-team bundles contain

The user controls exactly what data is included per bundle. Available data categories: stability scores over time, session logs with categories and costs, symptom entries, medication timing, PEM correlation results, spoon usage patterns, and trend summaries.

Bundles use industry-standard authenticated encryption with a passphrase-derived key. The backend stores ciphertext only (no server-side access to contents). The recipient opens the bundle in any browser using the passphrase, shared out-of-band by the user. Bundles are time-limited and revocable. No account is required on the provider's end.

Clinical mapping: A provider who receives a bundle can see patterns spanning weeks or months. They can correlate the user's self-reported PEM events with activity logs, see which categories cost the most spoons, and identify whether stability score trends align with changes in care.

What the app does not do

• Does not diagnose any condition
• Does not prescribe activity levels or rest periods
• Does not interpret biometric data clinically
• Does not replace clinical judgment or professional assessment
• Does not set alerts telling the user to stop (elevation notifications describe what happened; they do not instruct)
• Does not frame data evaluatively (no "good day" or "bad day"; trends are described as "trended up slightly," "held steady," or "showed more variability")
• Does not use gamification (no achievements, streaks, levels, or progress celebrations)
• Does not send data to any server during normal use

The app is a mirror, not a coach. It reflects the user's patterns so they (and their provider) can make informed decisions together.

Additional technical details

Location context (opt-in)

The app uses event-based location monitoring (never continuous GPS). This provides venue-level location context only. The "compare venues" feature shows which places correlate with higher or lower stability impact. Location context is off by default and can be disabled or deleted at any time.

Evening digest

A single notification at the user's configured time (default 19:00). The digest surfaces unexplained elevations for review. The user can tag, dismiss, or backfill sessions. All notifications are silent.