[Feature] Extend existing Highlights with contextual same-time baseline comparisons

[lutzkind]

Summary

Extend HealthLog’s existing Apple-Health-style highlight and personal-baseline infrastructure into contextual cards that compare the current value or partial-day trajectory with what is typical for the user at the relevant point in time.

The most important missing case is cumulative activity data such as steps:

You’re walking less than you usually do by this point.

• Today by 21:00: 1,834 steps
• Typical by 21:00: 5,111 steps
• Compact chart: today’s cumulative trajectory versus the personal same-time baseline

This should remain a transparent, deterministic insight layer rather than an AI-generated calculation.

Existing foundation to extend

This request is not greenfield. HealthLog already has several relevant foundations:

• src/components/insights/derived/sparkline-delta-tile.tsx is explicitly implemented as an Apple-Health-Highlights-style tile with a large value, trend arrow, inline sparkline, signed delta, framing text, and stale-data handling.
• src/components/insights/derived/vitals-dashboard.tsx already renders an Apple-Health-Highlights grid for personal-baseline and derived vital metrics.
• src/lib/insights/derived/baseline.ts already provides a server-authoritative rolling personal baseline using daily means, median, and MAD, with a seven-day history floor and explicit insufficient-data states.
• src/components/insights/derived/coach-read-strip.tsx already renders deterministic “usual range / today within-above-below” summaries from a server-resolved DTO.
• Dashboard charts and tiles already support prior-period comparisons and comparison deltas through the dashboard-layout and chart-overlay infrastructure.
• src/lib/insights/signals-of-day.ts already computes deterministic latest-versus-7-day/30-day signals for several metrics.

The requested work is therefore to generalize and connect these existing systems, not create a second highlight framework or duplicate measurement models.

Current gap

The existing baseline and highlight surfaces mainly cover completed daily means, latest readings, derived values, or prior-period comparisons.

They do not currently provide the key Apple Health behavior for cumulative intraday metrics:

Compare today’s accumulated value with the user’s typical accumulated value at the same local time.

The current Signals of the Day implementation deliberately excludes steps because the ingested rows are partial-day fragments and the newest raw row is not a completed daily total. That exclusion is correct for the current latest-reading calculation, but it leaves steps and similar activity metrics without an honest contextual highlight.

Proposed extension

Add a shared server-authoritative contextual-highlight contract that can reuse the existing highlight components while allowing each metric archetype to define its appropriate comparison strategy.

A highlight should be able to provide:

• Metric identifier, label, unit, and route.
• Short deterministic observation.
• Current/latest value.
• Baseline value or typical range.
• Signed absolute and percentage difference where meaningful.
• Current series and comparison series where appropriate.
• Baseline kind, lookback window, local cutoff time, and coverage.
• Sufficient/insufficient-data state and reason.
• Source/provenance metadata.

The web and native iOS clients should consume the same resolved comparison DTO even when presentation differs.

Metric-specific comparison strategies

1. Cumulative intraday metrics

Examples:

• Steps
• Active energy
• Exercise minutes
• Walking/running distance
• Flights climbed

Required behavior:

• Aggregate all valid samples into the user’s local calendar day.
• Build a cumulative intraday curve.
• Compare the current cumulative value with the typical cumulative value at the same local time.
• Compare curve-to-curve, not today’s partial value with an average completed-day total.
• Do not treat an unfinished day as a completed-day result.
• Handle overlapping or duplicate source samples according to the existing canonical-source/deduplication rules.

2. Nightly or session metrics

Examples:

• Sleep duration and timing
• Time in bed
• Workout duration

Required behavior:

• Compare the latest completed session with a recent personal baseline.
• Keep main sleep and naps distinct where the data model supports that distinction.
• Reuse interval-union and source-quality logic rather than summing overlapping raw rows.

3. Snapshot and trend metrics

Examples:

• Weight
• Resting heart rate
• HRV
• Respiratory rate

Required behavior:

• Reuse the existing baseline and SparklineDeltaTile infrastructure where possible.
• Compare a robust latest value or short rolling trend with the appropriate personal baseline.
• Avoid overstating one noisy sample.

4. Dense or highly variable metrics

Examples:

• Blood glucose
• Pulse
• Oxygen saturation

Required behavior:

• Use an appropriate daily shape, range, time-matched value, or summary rather than one misleading average.
• Return insufficient when an honest comparison cannot be produced.

Baseline requirements

The comparison must account for:

• User timezone and local-day boundaries.
• Current local cutoff time for partial-day comparisons.
• Minimum valid-day and sample coverage.
• Incomplete days and missing intervals.
• Weekday/weekend differences when enough history exists.
• Source or device changes.
• Duplicate or overlapping samples.
• Outliers and unusually sparse days.
• Median or robust typical ranges where an arithmetic mean is misleading.
• A documented or exposed lookback period.

The UI must clearly distinguish:

• Personal baseline.
• Prior-period comparison.
• Population or clinical reference range.

These are different comparison concepts and must not be conflated.

Presentation

Reuse or extend the existing highlight grammar rather than introducing an unrelated card family.

For an expanded contextual highlight, support:

• Plain-language comparison headline.
• Current value and typical value/range.
• Compact current-versus-baseline chart.
• Baseline period and coverage detail.
• Link to the existing metric detail page.
• Hide/disable control.

For cumulative metrics, the chart should be capable of rendering two aligned trajectories, not only a single sparkline.

Highlight selection

The dashboard should remain bounded:

• Show only a small number of useful highlights.
• Prioritize meaningful deviations, relevant completed summaries, and stable improvements.
• Avoid repeatedly surfacing the same unchanged message.
• Permit users to hide a card or disable highlights for a metric.
• Avoid alarming language for ordinary variation.
• Never infer a cause from the comparison alone.

Relationship to existing AI surfaces

The comparison and wording template should be deterministic and inspectable.

Coach or Daily Briefing may later explain an already-computed highlight, but they should not be required to calculate it and must not invent a cause.

Example:

Your steps were below your usual level by 21:00. This comparison alone does not explain why.

Suggested first phase

Start with cumulative activity metrics because they represent the clearest missing capability:

1. Steps
2. Active energy
3. Exercise duration
4. Walking/running distance

Then generalize the same contract to sleep/session and dense metrics while continuing to reuse the existing baseline tiles for vitals.

Acceptance criteria

• The implementation extends or reuses the existing highlight, baseline, chart, layout, and provenance systems rather than creating parallel data models.
• A server-authoritative contextual-highlight DTO is available to both web and iOS.
• Steps can compare today’s cumulative total with the personal baseline at the same local time.
• Cumulative metrics can return aligned current and typical trajectories.
• Partial days are never compared as if they were completed days.
• Nightly, session, snapshot, trend, and dense metrics can register different comparison strategies.
• The response exposes lookback, local cutoff, coverage, baseline kind, and sufficient-data status.
• Sparse, incomplete, duplicate, overlapping, and source-change data cannot silently produce a misleading comparison.
• Personal baselines remain distinct from clinical ranges and prior-period overlays.
• Wording is deterministic, neutral, and non-causal.
• Users can hide or disable highlights.
• iOS and web use the same comparison contract.
• Tests cover timezone boundaries, DST where applicable, partial days, weekday/weekend baselines, missing coverage, outliers, duplicate/overlapping samples, source changes, and insufficient-data states.

Related issues

• [Feature] Extend personal pattern discovery across behavioral, treatment, and environmental factors #616 — Personal pattern discovery and Coach explanations.
• [Feature] Allow an adaptive Personal Health Score based on available and enabled pillars #617 — Adaptive Personal Health Score pillars.
• [Feature] Configurable Table View for Measurements with Aggregation and Export #636 — Configurable measurement table view and export.

These are complementary but do not cover same-time cumulative comparisons and generalized contextual highlight cards.

[MBombeck]

This is the best-argued feature request in the tracker, @lutzkind, and the reason is that you did the part I would otherwise have had to do: you found the six pieces that already exist and framed the work as connecting them rather than building a second framework. The observation that Signals of the Day deliberately excludes steps, and that the exclusion is correct for a latest-reading calculation while leaving cumulative metrics without an honest highlight, is exactly the right diagnosis.

I am not going to pretend it is next. Reliability work comes first and there is a lot of it. But I owe you something better than the "captured as a roadmap item" I have written to you several times this week, because I checked this morning and the roadmap document contains none of them. That was a comfortable thing to say rather than a true one, and I am sorry.

So, concretely. This one, the adaptive health score you filed, and the Coach retrieval window all share a root that none of the three reports names, because it is not visible from outside: the personalisation layer personalises the data and not the yardstick. The baseline adapts to you; the score's four pillars, the Coach's window and the signal set do not. Three fixed rulers measuring a moving record. That is what the feature round after the reliability work should be about, and your same-time baseline is the clearest example of what it looks like when done right.

Leaving this open. When it moves you will hear it here, and if it stops being realistic you will hear that instead.

[MBombeck]

v1.34.0 ships same-time baseline comparisons for steps, active energy, distance, and flights: today's running total now compares against what is typical for you at this same hour, not just your latest reading. It needs at least two weeks of your own history before it shows anything, and says so honestly until then. This new hero item can be turned on or off from Dashboard settings. See the v1.34.0 CHANGELOG entry for the full write-up. Refs #649.