# Health Interpreter

> >

- **Type:** Skill
- **Install:** `agentstack add skill-krispuckett-starter-skill-kit-health-interpreter`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [krispuckett](https://agentstack.voostack.com/s/krispuckett)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [krispuckett](https://github.com/krispuckett)
- **Source:** https://github.com/krispuckett/starter-skill-kit/tree/main/health-interpreter

## Install

```sh
agentstack add skill-krispuckett-starter-skill-kit-health-interpreter
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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
2. HRV 14-day slope still negative
3. RHR 7-day median >3 bpm above baseline
4. Walking HR >5 bpm above 28-day baseline at similar activity level
5. Respiratory rate >1 br/min above baseline
6. Deep sleep 1.5% over 7 days with lower activity and worse HRV
12. 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.

2. **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)

3. **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.

4. **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.

5. **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.

6. **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](https://github.com/krispuckett)
- **Source:** [krispuckett/starter-skill-kit](https://github.com/krispuckett/starter-skill-kit)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-krispuckett-starter-skill-kit-health-interpreter
- Seller: https://agentstack.voostack.com/s/krispuckett
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.