Health Interpreter

Health Interpreter

An evidence-based framework for interpreting wearable health data. Built from real experience tracking health metrics through chronic illness, recovery, and performance training — then abstracted into a system anyone can use.

Core philosophy: orientation, not optimization. Weekly trends matter more than daily scores. Your body is your own reference point. Population norms are context, not targets.

Setup

1. Copy profile-template.md to your project and fill in your personal data
2. Establish your baselines over 14-28 days of normal life (instructions in the template)
3. Point the skill at your profile: reference the filled-in profile in your conversations

The skill works without a profile, but it's dramatically more useful with one.

---

1. The Orientation Model

Don't optimize. Orient. Every morning, check three things:

The Three Questions

1. Sleep duration — Enough or not? (7+ hours is the goal)
2. HRV trend — 3-day direction (rising, stable, falling)
3. Active disruptors — GI issues, medication changes, illness, yesterday's strain, alcohol, poor sleep, high stress

What the Answers Mean

| Sleep | HRV Trend | Disruptors | Capacity | |-------|-----------|------------|----------| | Good (7+ hr) | Rising or stable | None | Full. Push if you want to. | | Good | Rising or stable | Minor (1 drink, mild stress) | Near full. Proceed but don't max out. | | Short OR | Falling | — | Reduced. Protect energy. High-value work only. | | Any | Any | Multiple active | Recovery day. Triage obligations. | | — | Falling 3+ days | — | Investigate. Something changed — find it. |

This isn't a prescription to avoid things. It's situational awareness.

---

2. Metric Interpretation Framework

For every metric below, the same hierarchy applies:

Comparison Order (Always)

1. Your 28-day personal median = primary anchor
2. Your 7-day median vs 28-day median = current state
3. 14-day slope = intermediate trend direction
4. Population norms = secondary context only
5. Illness/disruptor context = if active, interpret metrics as temporarily suppressed

Rolling Windows

• 7-day = "How am I doing this week?" (acute state)
• 14-day = "Are interventions working?" (require ≥10 valid data points)
• 28-day = "What is my normal right now?" (re-lock only during stable periods)

Re-baseline rule: Only recalculate your 28-day baseline when ≥21 of 28 days are free from flares, travel, alcohol, acute illness, or major disruptions. Otherwise, keep the older stable baseline.

---

2A. Heart Rate Variability (HRV / SDNN)

What it measures: Parasympathetic nervous system tone. Higher = better recovery capacity.

Critical device note: Apple Watch reports SDNN, not RMSSD. Most competitors (Garmin, Oura, WHOOP) report RMSSD. These are different measurements with different norms — cross-device HRV comparisons are meaningless. The ESC Task Force 24-hour SDNN thresholds (50/100 ms) do NOT apply to Apple's short-epoch averaged SDNN [23].

Apple Watch accuracy: Underestimates SDNN by ~8 ms (MAPE 29%) [13]. Use 7-day rolling medians, never single readings. Trend direction is reliable; absolute values are not.

Threshold Zones (vs YOUR 28-day baseline)

| Zone | Range | Action | |------|-------|--------| | Green | ≥ baseline | Planned training may proceed | | Yellow | 5-10% below | Reduce intensity one zone. Zone 2 only. | | Orange | 10-20% below | Easy movement or rest | | Red | >20% below, or 2-day collapse >25% | Full rest. Assess sleep, GI, stress, illness. |

Decision Rules

• HRV ≥ baseline → full planned training [2][3]
• HRV falls below 10-day mean minus 1 SD or 2-day downward trend → swap intensity for low intensity or rest [2]
• HRV >20% below for 3+ days → no threshold/tempo work, no hard lifting
• HRV improves for 14 days while RHR falls → interventions are working, even if VO2max lags
• HRV falling while deep sleep falls and GI symptoms worsen → likely vagal withdrawal from inflammatory stress [8][9]

What Tanks HRV

• Alcohol (even 1-2 drinks can suppress next-day HRV by 20-30%)
• Poor sleep (+7 bpm for 3 days, or +10 bpm single day | Investigate immediately |

Decision Rules

• RHR rises >3 bpm AND HRV falls >10% → real physiologic strain, not device noise
• RHR rises >5 bpm but HRV unchanged and sleep was short → likely acute sleep debt
• RHR rises >5 bpm for >3 days with worsening symptoms → likely inflammatory process
• RHR rises while respiratory rate rises and SpO2 worsens → prioritize sleep/breathing investigation
• RHR drops toward pre-illness baseline → green light to cautiously add training volume

---

2C. Sleep

Key components:

• Deep sleep (N3): Physical restoration, growth hormone release. Target: 1-2 hours/night
• REM: Cognitive consolidation, emotional processing. Target: 1.5-2 hours/night
• Sleep efficiency: Time asleep / time in bed. Target: >85%
• HR dip during sleep: Heart rate should drop 10-20% (parasympathetic dominance)

Apple Watch accuracy: Deep sleep sensitivity is only 50.5% vs polysomnography — it systematically underestimates by ~43 minutes [14]. Treat Apple Watch deep sleep as a floor estimate. Sleep/wake detection accuracy is 93%, which is solid. Trust trends, not absolutes.

Critical parsing note: Apple Health stores "InBed" and "Asleep" as separate values. InBed ≠ Asleep. Including InBed in sleep totals inflates duration by 2-6 hours/night. This is the #1 Apple Health data parsing error.

Flags Worth Investigating

• HR dip 90 min → circadian disruption; reset to ±30 min window

---

2D. SpO2 (Blood Oxygen)

Apple Watch accuracy: Limits of agreement ±2.7% to ±5.9%, with outliers up to 15% [15]. 14% of readings show +1.5 for 3+ nights |

Decision Rules

• RR rises with low HRV and high RHR → systemic stress or inflammation
• RR rises with low SpO2 and fragmented sleep → breathing-related sleep disruption
• RR rises with GI symptoms (bloating, pain, reflux) → consider diaphragm restriction, sympathetic activation
• RR >20 sustained → assess for respiratory infection, worsening sleep-disordered breathing

---

2F. Walking Heart Rate

Walking HR is one of the most sensitive markers of cardiovascular fitness and systemic strain. It responds faster than VO2max to deconditioning or recovery.

| Zone | Range vs Baseline | |------|-------------------| | Green | Within ±3 bpm | | Yellow | +4 to +6 bpm | | Orange | +7 to +10 bpm | | Red | >+10 bpm sustained for 7+ days |

Decision Rules

• Walking HR rises >5 bpm with unchanged step count → deconditioning, fatigue, or inflammation
• Walking HR rises while weight rises and HRV falls → reduced efficiency under inflammatory/metabolic load
• Walking HR falls over 14-28 days while cardiac drift stays low → aerobic recovery returning before VO2max improves
• Walking HR is often the FIRST metric to improve when an intervention is working — watch it weekly

---

2G. Heart Rate Recovery (HRR)

The drop in heart rate during the first minute after stopping exercise.

| HRR1 | Classification | Action | |------|---------------|--------| | >25 bpm | Good autonomic recovery | Positive signal | | 18-25 bpm | Acceptable for most contexts | Continue protocol | | 13-17 bpm | Below expected | Assess overtraining, illness, sleep quality | | 1 week, medical evaluation. |

Decision Rules

• HRR1 8% | Significant | Probably above true aerobic zone, or: dehydration, poor fueling, illness |

| >10% | Above threshold or acute fatigue | Full rest day follows |

Cardiac Efficiency

Calculate per exercise session: average speed ÷ average heart rate. Track over time. Improving efficiency with the same HR = genuine aerobic adaptation.

---

2J. Training Load (TRIMP) and ACWR

The acute-to-chronic workload ratio (ACWR) is the most evidence-based tool for load management [10].

TRIMP Calculation

For cardio: TRIMP = duration(min) × HRr × 0.64 × e^(1.92 × HRr) Where HRr = (avg HR - resting HR) / (max HR - resting HR)

For strength: sRPE Load = duration(min) × session RPE (0-10 scale)

ACWR Thresholds

| ACWR | Zone | Action | |------|------|--------| | 0.85-1.35 | Productive | Proceed with plan [10] | | 1.36-1.50 | Caution | Monitor closely | | 1.51-1.70 | High risk | Only if readiness is clearly green | | >1.70 | Spike | Reduce load for next 3-7 days | | 2 weeks) | Reintroduce load gradually |

Decision Rules

• ACWR >1.35 AND HRV down >10% → cap all training at easy/zone 2 for 72 hours
• ACWR >1.50 regardless of HRV → cancel hard workouts for the week [10]
• Low chronic load + acute spike = higher injury risk than same ACWR from high base
• ACWR 14 days → reintroduce gradually; don't perpetuate underloading

---

3. Composite Scores

3A. Morning Readiness Score (0-100)

Purpose: decide training intensity for the day.

| Component | Max Points | What It Measures | |-----------|-----------|------------------| | HRV vs 28-day baseline | 30 | Autonomic state | | Resting HR vs 28-day baseline | 20 | Inflammatory strain | | Sleep (quantity + efficiency + stages) | 20 | Recovery quality | | Respiratory rate vs baseline | 10 | Systemic stress | | Overnight oxygenation | 10 | Sleep-breathing burden | | Prior-day training load vs chronic | 10 | Load management |

HRV Subscore (0-30)

• 7-day SDNN ≥ 28-day median → 30
• 5-10% below → 22
• 10-20% below → 12
• >20% below → 0

RHR Subscore (0-20)

• 7-day RHR ≤ baseline +1 bpm → 20
• +2 to +3 bpm → 14
• +4 to +5 bpm → 7
• >+5 bpm → 0

Sleep Subscore (0-20)

Start at 20, subtract:

• -6 if total sleep 90 min from 28-day norm

Respiratory Rate Subscore (0-10)

• Within ±0.5 br/min of baseline → 10
• +0.6 to +1.0 → 7
• +1.1 to +1.5 → 3
• >+1.5 → 0

Oxygenation Subscore (0-10)

• Overnight mean SpO2 within normal range, no clustering → 10
• Slightly below normal or scattered lows → 7
• Below normal range or recurrent lows with fragmentation → 3
• Well below normal or frequent clustered lows → 0

Training Load Subscore (0-10)

• ACWR 0.85-1.35 → 10
• ACWR 1.36-1.50 or 0.70-0.84 → 7
• ACWR 1.51-1.70 or 0.60-0.69 → 3
• ACWR >1.70 or 10% below 28-day baseline

1. HRV 14-day slope still negative
2. RHR 7-day median >3 bpm above baseline
3. Walking HR >5 bpm above 28-day baseline at similar activity level
4. Respiratory rate >1 br/min above baseline
5. Deep sleep 1.5% over 7 days with lower activity and worse HRV
6. ACWR >1.35 while HRV is suppressed

| Score | Level | Action | |-------|-------|--------| | 0-2 | Low systemic strain | Continue protocol | | 3-5 | Mild strain | Favor lifestyle correction (sleep, diet, stress) | | 6-8 | Likely active inflammatory/autonomic strain | Reduce training, review triggers | | 9-12 | High-probability flare state | Prioritize recovery and medical review if >72 hours |

---

4. Cross-Metric Pattern Detection

These patterns emerge when multiple metrics move together. Individual metrics fluctuate; clusters tell the story.

Pattern 1: Inflammatory / GI Flare

Cluster: HRV ↓>10-20% + RHR ↑>3-5 bpm + deep sleep ↓ + RR ↑>1 br/min + walking HR ↑>5 bpm + symptoms Mechanism: Inflammatory cytokines activate vagal afferents, triggering autonomic withdrawal. Sympathetic dominance raises HR and suppresses recovery [7][8][9]. Action: Remove hard training 48-72 hr. Clean up diet. No alcohol, late meals, or known triggers. If >7 days, escalate medically.

Pattern 2: Sleep-Disordered Breathing

Cluster: Overnight SpO2 below normal or clustered dips + RR elevated + deep sleep low + fragmented sleep + RHR elevated on waking + HRV suppressed + daytime fatigue Mechanism: Cyclical hypoxemia fragments sleep and triggers sympathetic activation. Action: Prioritize overnight oximetry or home sleep study. Avoid alcohol and large late meals. Favor side-sleeping. Reduce training intensity.

Pattern 3: Iron-Limited Adaptation

Cluster: Ferritin 1.35 (especially >1.50) + HRV ↓>10% + RHR ↑>3 bpm + cardiac drift worsening + subjective soreness/fatigue Action: Cut weekly load 30-50%. Easy movement only. Resume intensity after HRV/RHR normalize for 3+ days [10].

Pattern 5: Positive Adaptation

Cluster: HRV trending up over 14 days + RHR trending down + walking HR decreasing + sleep duration/regularity stable + cardiac drift ≤3-4% + VO2max stable or rising over 28-56 days Meaning: Genuine improvement in autonomic efficiency and aerobic economy. Action: Progress volume 5-10% per week max. Add intensity only if ACWR ≤1.35 and recovery metrics stable.

Pattern 6: Pre-Symptomatic Relapse Detection

Cluster: Gradual HRV decline over 3-5 days + slow RHR elevation + increased sleep fragmentation + reduced deep sleep — all BEFORE overt symptoms appear Mechanism: Autonomic withdrawal often precedes symptom onset by days. If you have a chronic condition with flare patterns, your wearable may catch the decline before you feel it. Action: If these markers trend negatively for 3-5 consecutive days, pre-emptively tighten your management protocol. Don't wait for symptoms to confirm what the data already shows.

---

5. Daily Decision Tree

Step 1: Medical Red-Flag Gate

IF ANY of the following → skip training, seek medical attention:

• Chest pain, syncope, new irregular heartbeat
• Severe shortness of breath at rest
• Persistent resting SpO2 ≤90%
• Overnight mean SpO2 10 bpm above baseline for >3 days with systemic illness signs

Step 2: Compute Morning Readiness Score

• ≥85 → full planned training
• 70-84 → reduce intensity one category
• 55-69 → recovery session only
• 70
• IF overnight oxygenation poor → no threshold/VO2 work
• IF ACWR >1.50 → no intensity regardless of readiness
• IF ferritin low and fatigue high → aerobic maintenance, not performance chasing

Step 4: Choose Activity Level

| Readiness + Context | Activity | |-------------------|----------| | Green + stable recovery + ACWR ≤1.35 | Hard training OK (tempo, threshold, heavy lifting) | | Yellow | Moderate only (zone 2, moderate lifting) | | Orange | Easy movement (walking, mobility, technique work) | | Red | Full recovery |

---

6. Research Integrity Rules

These rules are non-negotiable. They're what separate useful health interpretation from noise.

1. No fabricated citations. Every claim references real, published research. If no evidence exists, say so. See references/evidence-base.md for the full citation list with study quality ratings.

1. Classify evidence strength. Always note whether a recommendation is based on:

• Strong evidence (RCT, meta-analysis, large prospective cohort)
• Moderate evidence (observational, systematic review of observational)
• Limited evidence (expert consensus, case series, mechanistic reasoning)

1. Individual baselines over population norms. Your 28-day median is more informative than any percentile chart. Population norms provide context; they don't define your health.

1. Device accuracy awareness. Apple Watch is a consumer device, not medical equipment. Know its limits (see accuracy table below) and don't over-interpret noise.

1. Never diagnose. Interpret and flag for medical review. "This pattern is consistent with X — discuss with your doctor" is appropriate. "You have X" is not.

1. Actionable thresholds must clear BOTH physiologic and device noise. A single-day HRV change of 5% could be real or could be measurement error. Sustained changes over 3+ days that exceed device noise margins are meaningful.

Apple Watch Accuracy Reference

| Metric | Accuracy vs Gold Standard | Key Limitation | Practical Rule | |--------|--------------------------|----------------|----------------| | Heart Rate (rest/walk) | Mean bias -0.27 bpm, LoA ±7 bpm [17] | Worsens at high intensity | Trust for Zone 2 and resting. Caution during HIIT. | | HRV (SDNN) | Underestimates ~8 m

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: krispuckett
• Source: krispuckett/starter-skill-kit
• License: MIT

Install and usage instructions live in the source repository linked above.