@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/healthkit/SKILL.md

@@ -1,339 +1,300 @@
 ---
 name: healthkit
-description: "Read, write, and query Apple Health data using HealthKit. Covers HKHealthStore authorization, sample queries, statistics queries, statistics collection queries for charts, saving HKQuantitySample data, background delivery, workout sessions with HKWorkoutSession and HKLiveWorkoutBuilder, HKUnit, and HKQuantityTypeIdentifier values. Use when integrating with Apple Health, displaying health metrics, recording workouts, or enabling background health data delivery."
+description: "HealthKit on iOS, iPadOS, watchOS and visionOS: HKHealthStore authorization, sample, statistics and chart-ready collection queries, saving HKQuantitySample values, background delivery, live workouts (HKWorkoutSession, HKLiveWorkoutBuilder), HKUnit, HKQuantityTypeIdentifier. Use when reading, writing or querying Health data, integrating with the Health app, displaying health metrics, logging workouts or turning on background delivery."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # HealthKit
 
-Read and write health and fitness data from the Apple Health store. Covers authorization, queries, writing samples, background delivery, and workout sessions. Targets Swift 6.3 / iOS 26+.
+HealthKit is the store behind the Health app. This skill covers asking for
+access, reading with queries, writing samples, getting woken up for new data,
+and running live workouts. Examples use Swift 6.3 and iOS 26.
 
-## Contents
+## Setup and availability
 
-- [Setup and Availability](#setup-and-availability)
-- [Authorization](#authorization)
-- [Reading Data: Sample Queries](#reading-data-sample-queries)
-- [Reading Data: Statistics Queries](#reading-data-statistics-queries)
-- [Reading Data: Statistics Collection Queries](#reading-data-statistics-collection-queries)
-- [Writing Data](#writing-data)
-- [Background Delivery](#background-delivery)
-- [Workout Sessions](#workout-sessions)
-- [Common Data Types](#common-data-types)
-- [HKUnit Reference](#hkunit-reference)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+### Project configuration
 
-## Setup and Availability
+1. In Xcode, add the HealthKit capability to the target. Doing so writes the
+   entitlement for you.
+2. Info.plist needs `NSHealthShareUsageDescription` if the app reads and
+   `NSHealthUpdateUsageDescription` if it writes.
+3. To be launched for new data, also tick the Background Delivery option under
+   the HealthKit capability.
 
-### Project Configuration
-
-1. Enable the HealthKit capability in Xcode (adds the entitlement)
-2. Add `NSHealthShareUsageDescription` (read) and `NSHealthUpdateUsageDescription` (write) to Info.plist
-3. For background delivery, enable the "Background Delivery" sub-capability
-
-### Availability Check
-
-Always check availability before calling other HealthKit APIs. Health data is
-available on iOS, watchOS, visionOS, iPadOS 17+, and iOS apps running on
-Vision Pro. It is unavailable on iPadOS 16 or earlier and may be restricted by
-managed device policy.
+### Is health data available?
 
 ```swift
 import HealthKit
 
-guard HKHealthStore.isHealthDataAvailable() else {
-    // Health data is unavailable or restricted on this device.
-    return
+enum Health {
+    static let store = HKHealthStore()
+    static var isUsable: Bool { HKHealthStore.isHealthDataAvailable() }
 }
-
-let healthStore = HKHealthStore()
 ```
 
-Create a single `HKHealthStore` instance and reuse it throughout your app. It
-is thread-safe. If HealthKit is optional, review Xcode's generated
-`UIRequiredDeviceCapabilities` `healthkit` entry so unsupported devices are not
-excluded unintentionally.
+- Check `HKHealthStore.isHealthDataAvailable()` first; nothing else in HealthKit should run before it.
+- Data is available on iPhone, Apple Watch, Apple Vision Pro (including iPhone
+  apps running there) and iPad on iPadOS 17 and later.
+- iPads still on iPadOS 16 or older have no Health store, and device
+  management policy can switch it off anywhere.
+- Make one `HKHealthStore` for the whole app and share it; the class is
+  thread-safe.
+- Enabling the capability can make Xcode add `healthkit` to
+  `UIRequiredDeviceCapabilities`. If HealthKit is an optional feature, check
+  that entry so devices without Health are not excluded from installing.
 
 ## Authorization
 
-Request only the types your app genuinely needs. App Review rejects apps that over-request.
+Ask only for the types the feature uses. Requesting more than needed is a
+common App Review rejection.
 
 ```swift
-func requestAuthorization() async throws {
-    let typesToShare: Set<HKSampleType> = [
-        HKQuantityType(.stepCount),
-        HKQuantityType(.activeEnergyBurned)
-    ]
+import HealthKit
 
-    let typesToRead: Set<HKObjectType> = [
+func requestSleepAppAccess(_ store: HKHealthStore) async throws {
+    let writes: Set<HKSampleType> = [HKQuantityType(.activeEnergyBurned)]
+    let reads: Set<HKObjectType> = [
         HKQuantityType(.stepCount),
         HKQuantityType(.heartRate),
-        HKQuantityType(.activeEnergyBurned),
         HKCharacteristicType(.dateOfBirth)
     ]
-
-    try await healthStore.requestAuthorization(
-        toShare: typesToShare,
-        read: typesToRead
-    )
+    try await store.requestAuthorization(toShare: writes, read: reads)
 }
 ```
 
-### Checking Authorization Status
+### What the status tells you
 
-`authorizationStatus(for:)` reports write/share authorization. HealthKit does
-not reveal whether read permission was granted or denied. If the user denies
-read access, queries return only samples your app successfully saved, which may
-look like empty or partial data.
+`authorizationStatus(for:)` reports only on sharing (writing). HealthKit never
+reveals whether a read request was allowed, to protect privacy. When reading is
+denied, queries simply return the samples this app saved itself, which looks
+like an empty or incomplete history.
 
 ```swift
-let status = healthStore.authorizationStatus(
-    for: HKQuantityType(.stepCount)
-)
-
-switch status {
-case .notDetermined:
-    // Haven't requested yet -- safe to call requestAuthorization
-    break
-case .sharingAuthorized:
-    // User granted write access
-    break
-case .sharingDenied:
-    // User denied write access (read denial is indistinguishable from "no data")
-    break
-@unknown default:
-    break
+import HealthKit
+
+func canSave(_ type: HKObjectType, store: HKHealthStore) -> Bool? {
+    switch store.authorizationStatus(for: type) {
+    case .notDetermined: return nil
+    case .sharingAuthorized: return true
+    case .sharingDenied: return false
+    @unknown default: return false
+    }
 }
 ```
 
-## Reading Data: Sample Queries
+`nil` here means the app may still ask.
 
-Use `HKSampleQueryDescriptor` (async/await) for one-shot reads. Prefer descriptors over the older callback-based `HKSampleQuery`.
+## Reading samples
+
+For one-off reads use `HKSampleQueryDescriptor` with async/await rather than
+the older callback-based `HKSampleQuery`.
 
 ```swift
-func fetchRecentHeartRates() async throws -> [HKQuantitySample] {
-    let heartRateType = HKQuantityType(.heartRate)
+import HealthKit
 
-    let descriptor = HKSampleQueryDescriptor(
-        predicates: [.quantitySample(type: heartRateType)],
+func latestPulseReadings(_ store: HKHealthStore) async throws -> [Double] {
+    let pulse = HKQuantityType(.heartRate)
+    let query = HKSampleQueryDescriptor(
+        predicates: [.quantitySample(type: pulse)],
         sortDescriptors: [SortDescriptor(\.endDate, order: .reverse)],
         limit: 20
     )
-
-    let results = try await descriptor.result(for: healthStore)
-    return results
-}
-
-// Extracting values from samples:
-for sample in results {
-    let bpm = sample.quantity.doubleValue(
-        for: HKUnit.count().unitDivided(by: .minute())
-    )
-    print("\(bpm) bpm at \(sample.endDate)")
+    let perMinute = HKUnit.count().unitDivided(by: .minute())
+    let samples = try await query.result(for: store)
+    return samples.map { $0.quantity.doubleValue(for: perMinute) }
 }
 ```
 
-## Reading Data: Statistics Queries
+## Aggregates: statistics queries
 
-Use `HKStatisticsQueryDescriptor` for aggregated single-value stats (sum, average, min, max).
+`HKStatisticsQueryDescriptor` returns one aggregated value: a sum, average,
+minimum or maximum.
 
 ```swift
-func fetchTodayStepCount() async throws -> Double? {
-    let calendar = Calendar.current
-    let startOfDay = calendar.startOfDay(for: Date())
-    let endOfDay = calendar.date(byAdding: .day, value: 1, to: startOfDay)!
-
-    let predicate = HKQuery.predicateForSamples(
-        withStart: startOfDay, end: endOfDay
-    )
-    let stepType = HKQuantityType(.stepCount)
-    let samplePredicate = HKSamplePredicate.quantitySample(
-        type: stepType, predicate: predicate
-    )
+import HealthKit
 
+func stepsToday(_ store: HKHealthStore) async throws -> Double {
+    let calendar = Calendar.current
+    let midnight = calendar.startOfDay(for: .now)
+    guard let tomorrow = calendar.date(byAdding: DateComponents(day: 1), to: midnight) else { return 0 }
+    let window = HKQuery.predicateForSamples(withStart: midnight, end: tomorrow)
     let query = HKStatisticsQueryDescriptor(
-        predicate: samplePredicate,
+        predicate: .quantitySample(type: HKQuantityType(.stepCount), predicate: window),
         options: .cumulativeSum
     )
-
-    let result = try await query.result(for: healthStore)
-    return result?.sumQuantity()?.doubleValue(for: .count())
+    let total = try await query.result(for: store)
+    return total?.sumQuantity()?.doubleValue(for: .count()) ?? 0
 }
 ```
 
-**Options by data type:**
-- Cumulative types (steps, calories): `.cumulativeSum`
-- Discrete types (heart rate, weight): `.discreteAverage`, `.discreteMin`, `.discreteMax`
+Pick the option from the kind of data:
 
-## Reading Data: Statistics Collection Queries
+| Data | Examples | Options |
+|---|---|---|
+| cumulative | steps, energy burned | `.cumulativeSum` |
+| discrete | heart rate, body mass | `.discreteAverage`, `.discreteMin`, `.discreteMax` |
 
-Use `HKStatisticsCollectionQueryDescriptor` for time-series data grouped into intervals -- ideal for charts.
+## Time series: statistics collection queries
 
-```swift
-func fetchDailySteps(forLast days: Int) async throws -> [(date: Date, steps: Double)] {
-    let calendar = Calendar.current
-    let endDate = calendar.startOfDay(
-        for: calendar.date(byAdding: .day, value: 1, to: Date())!
-    )
-    let startDate = calendar.date(byAdding: .day, value: -days, to: endDate)!
+`HKStatisticsCollectionQueryDescriptor` buckets data into equal intervals,
+which is exactly what a chart needs. It takes a `predicate`, `options`, an
+`anchorDate` that aligns the buckets and `intervalComponents` such as
+`DateComponents(day: 1)`.
 
-    let predicate = HKQuery.predicateForSamples(
-        withStart: startDate, end: endDate
-    )
-    let stepType = HKQuantityType(.stepCount)
-    let samplePredicate = HKSamplePredicate.quantitySample(
-        type: stepType, predicate: predicate
-    )
+```swift
+import HealthKit
 
+func dailyEnergy(_ store: HKHealthStore, between start: Date, and end: Date) async throws -> [(Date, Double)] {
     let query = HKStatisticsCollectionQueryDescriptor(
-        predicate: samplePredicate,
+        predicate: .quantitySample(type: HKQuantityType(.activeEnergyBurned),
+                                   predicate: HKQuery.predicateForSamples(withStart: start, end: end)),
         options: .cumulativeSum,
-        anchorDate: endDate,
+        anchorDate: start,
         intervalComponents: DateComponents(day: 1)
     )
-
-    let collection = try await query.result(for: healthStore)
-    var dailySteps: [(date: Date, steps: Double)] = []
-
-    collection.statisticsCollection.enumerateStatistics(
-        from: startDate, to: endDate
-    ) { statistics, _ in
-        let steps = statistics.sumQuantity()?
-            .doubleValue(for: .count()) ?? 0
-        dailySteps.append((date: statistics.startDate, steps: steps))
+    var days: [(Date, Double)] = []
+    try await query.result(for: store).enumerateStatistics(from: start, to: end) { bucket, _ in
+        days.append((bucket.startDate, bucket.sumQuantity()?.doubleValue(for: .kilocalorie()) ?? 0))
     }
-
-    return dailySteps
+    return days
 }
 ```
 
-### Long-Running Collection Query
+### Keeping a chart live
 
-Use `results(for:)` (plural) to get an `AsyncSequence` that emits updates as new data arrives:
+`results(for:)`, plural, returns an `AsyncSequence` that yields a fresh
+collection whenever matching data changes. Consume it in a `Task` with
+`for try await`. The descriptor is not `Sendable`, so mark the parameter
+`sending`; the caller hands it over and does not touch it again:
 
 ```swift
-let updateStream = query.results(for: healthStore)
+import HealthKit
 
-Task {
-    for try await result in updateStream {
-        // result.statisticsCollection contains updated data
+func followEnergy(_ query: sending HKStatisticsCollectionQueryDescriptor, store: HKHealthStore) -> Task<Void, Error> {
+    Task {
+        for try await update in query.results(for: store) {
+            _ = update.statisticsCollection
+        }
     }
 }
 ```
 
-## Writing Data
-
-Create `HKQuantitySample` objects and save them to the store.
+## Writing
 
 ```swift
-func saveSteps(count: Double, start: Date, end: Date) async throws {
-    let stepType = HKQuantityType(.stepCount)
-    let quantity = HKQuantity(unit: .count(), doubleValue: count)
-
-    let sample = HKQuantitySample(
-        type: stepType,
-        quantity: quantity,
-        start: start,
-        end: end
-    )
+import HealthKit
 
-    try await healthStore.save(sample)
+func logPushUps(_ reps: Double, over span: DateInterval, store: HKHealthStore) async throws {
+    let amount = HKQuantity(unit: .count(), doubleValue: reps)
+    let entry = HKQuantitySample(type: HKQuantityType(.pushCount), quantity: amount, start: span.start, end: span.end)
+    try await store.save(entry)
 }
-
 ```
 
-Your app can only delete samples it created. Samples from other apps or Apple Watch are read-only.
+An app may delete only the samples it wrote. Data from other apps or from
+Apple Watch is read-only to it.
 
-## Background Delivery
+## Background delivery
 
-Register for background updates so your app is launched when new data arrives. Requires the background delivery entitlement.
+Background delivery launches the app when new samples of a type arrive. It
+needs the background delivery entitlement and always works as a pair: an
+executed `HKObserverQuery` and a call to
+`enableBackgroundDelivery(for:frequency:)`.
 
 ```swift
-func enableStepCountBackgroundDelivery() async throws {
-    let stepType = HKQuantityType(.stepCount)
-
-    try await healthStore.enableBackgroundDelivery(
-        for: stepType,
-        frequency: .hourly
-    )
-}
-```
-
-**Pair with an `HKObserverQuery`** to handle notifications. Always call the completion handler:
+import HealthKit
 
-```swift
-let observerQuery = HKObserverQuery(
-    sampleType: HKQuantityType(.stepCount),
-    predicate: nil
-) { query, completionHandler, error in
-    defer { completionHandler() }  // Must call to signal done
-    guard error == nil else { return }
-    // Fetch new data, update UI, etc.
+func registerWeightUpdates(_ store: HKHealthStore, refresh: @escaping @Sendable () -> Void) async throws {
+    let weight = HKQuantityType(.bodyMass)
+    let watcher = HKObserverQuery(sampleType: weight, predicate: nil) { _, finished, error in
+        defer { finished() }
+        guard error == nil else { return }
+        refresh()
+    }
+    store.execute(watcher)
+    try await store.enableBackgroundDelivery(for: weight, frequency: .daily)
 }
-healthStore.execute(observerQuery)
 ```
 
-**Frequencies:** `.immediate`, `.hourly`, `.daily`, `.weekly`
-
-Set up observer queries as soon as the app launches, then call
-`enableBackgroundDelivery` once for the same sample type. The system persists
-the registration, wakes the app at most once per requested frequency, and
-enforces tighter caps for some types such as hourly step-count delivery on iOS.
-Background delivery is not supported on Simulator; test it on device.
-
-## Workout Sessions
-
-Use `HKWorkoutSession` and `HKLiveWorkoutBuilder` to track live workouts.
-`HKWorkoutSession` is available on iOS/iPadOS 17+, visionOS 1+, and watchOS 2+.
-`HKLiveWorkoutBuilder` is available on iOS/iPadOS 26+ and watchOS 5+, so gate
-live-builder code if supporting older iOS/iPadOS releases.
-
-On iPhone and iPad, live heart-rate collection requires a paired external heart
-rate sensor. Apple Watch sessions can collect high-frequency heart-rate data.
-For locked iPhone workouts, plan for the system's workout-data access flow
-before showing health metrics on the Lock Screen.
+- Frequencies: `.immediate`, `.hourly`, `.daily`, `.weekly`.
+- Order matters. Create the observer queries every time the app launches.
+  Register the type with `enableBackgroundDelivery` a single time; the system
+  keeps that registration across launches.
+- The frequency is a ceiling. The app is woken at most that often, and some
+  types are capped lower (step count on iOS is at most hourly).
+- Always call the observer's completion handler, here with `defer`.
+- Simulator does not support background delivery. Use a device.
+
+## Workout sessions
+
+Live workouts combine `HKWorkoutSession` with `HKLiveWorkoutBuilder`.
+
+| API | iOS / iPadOS | visionOS | watchOS |
+|---|---|---|---|
+| `HKWorkoutSession` | 17+ | 1+ | 2+ |
+| `HKLiveWorkoutBuilder` | 26+ | - | 5+ |
+
+- Apps that still deploy to iPhone or iPad releases before 26 must wrap the
+  live builder in an availability check.
+- iPhone and iPad have no built-in heart rate sensor; live heart rate there
+  requires a paired external sensor. Apple Watch sessions record high-frequency
+  heart rate on their own.
+- iPhone workouts often run with the phone locked. Before showing health
+  metrics on the Lock Screen, plan for the system flow that grants access to
+  workout data there.
 
 ```swift
-func startWorkout() async throws {
-    let configuration = HKWorkoutConfiguration()
-    configuration.activityType = .running
-    configuration.locationType = .outdoor
-
-    let session = try HKWorkoutSession(
-        healthStore: healthStore,
-        configuration: configuration
-    )
-    session.delegate = self
+import HealthKit
 
-    let builder = session.associatedWorkoutBuilder()
-    builder.dataSource = HKLiveWorkoutDataSource(
-        healthStore: healthStore,
-        workoutConfiguration: configuration
-    )
+@available(iOS 26.0, *)
+@MainActor
+final class RideRecorder: NSObject, HKWorkoutSessionDelegate {
+    private let store: HKHealthStore
+    private var session: HKWorkoutSession?
+    private var builder: HKLiveWorkoutBuilder?
+
+    init(store: HKHealthStore) { self.store = store }
+
+    func begin() async throws {
+        let setup = HKWorkoutConfiguration()
+        setup.activityType = .cycling
+        setup.locationType = .outdoor
+
+        let session = try HKWorkoutSession(healthStore: store, configuration: setup)
+        session.delegate = self
+        let builder = session.associatedWorkoutBuilder()
+        builder.dataSource = HKLiveWorkoutDataSource(healthStore: store, workoutConfiguration: setup)
+        self.session = session
+        self.builder = builder
+
+        let now = Date()
+        session.startActivity(with: now)
+        try await builder.beginCollection(at: now)
+    }
 
-    session.startActivity(with: Date())
-    try await builder.beginCollection(at: Date())
-}
+    func finish() async throws {
+        guard let activeSession = session, let activeBuilder = builder else { return }
+        activeSession.end()
+        try await activeBuilder.endCollection(at: .now)
+        _ = try await activeBuilder.finishWorkout()
+    }
 
-func endWorkout(
-    session: HKWorkoutSession,
-    builder: HKLiveWorkoutBuilder
-) async throws {
-    session.end()
-    try await builder.endCollection(at: Date())
-    try await builder.finishWorkout()
+    nonisolated func workoutSession(_ ride: HKWorkoutSession,
+                                    didChangeTo toState: HKWorkoutSessionState,
+                                    from fromState: HKWorkoutSessionState, date: Date) {}
+    nonisolated func workoutSession(_ ride: HKWorkoutSession, didFailWithError failure: Error) {}
 }
 ```
 
-For full workout lifecycle management including pause/resume, delegate handling, and multi-device mirroring, see [references/healthkit-patterns.md](references/healthkit-patterns.md).
+End in this order: `session.end()`, then `builder.endCollection(at:)`, then
+`builder.finishWorkout()`.
 
-## Common Data Types
+## Common data types
 
 ### HKQuantityTypeIdentifier
 
-| Identifier | Category | Unit |
+| Identifier | Group | Unit |
 |---|---|---|
 | `.stepCount` | Fitness | `.count()` |
 | `.distanceWalkingRunning` | Fitness | `.meter()` |
@@ -346,88 +307,76 @@ For full workout lifecycle management including pause/resume, delegate handling,
 | `.bodyMassIndex` | Body | `.count()` |
 | `.height` | Body | `.meter()` |
 | `.bodyFatPercentage` | Body | `.percent()` |
-| `.bloodGlucose` | Lab | `.gramUnit(with: .milli).unitDivided(by: .literUnit(with: .deci))` |
+| `.bloodGlucose` | Lab | mg/dL: `HKUnit.gramUnit(with: .milli).unitDivided(by: HKUnit.literUnit(with: .deci))` |
 
 ### HKCategoryTypeIdentifier
 
-Common category types: `.sleepAnalysis`, `.mindfulSession`, `.appleStandHour`
+Frequently used: `.sleepAnalysis`, `.mindfulSession`, `.appleStandHour`.
 
 ### HKCharacteristicType
 
-Read-only user characteristics include `.dateOfBirth`, `.biologicalSex`,
-`.bloodType`, `.fitzpatrickSkinType`, `.wheelchairUse`, and `.activityMoveMode`.
+Read-only values the user sets once: `.dateOfBirth`, `.biologicalSex`,
+`.bloodType`, `.fitzpatrickSkinType`, `.wheelchairUse`, `.activityMoveMode`.
 
-## HKUnit Reference
+## HKUnit quick reference
 
 ```swift
-// Basic units
-HKUnit.count()                              // Steps, counts
-HKUnit.meter()                              // Distance
-HKUnit.mile()                               // Distance (imperial)
-HKUnit.kilocalorie()                        // Energy
-HKUnit.joule(with: .kilo)                   // Energy (SI)
-HKUnit.gramUnit(with: .kilo)                // Mass (kg)
-HKUnit.pound()                              // Mass (imperial)
-HKUnit.percent()                            // Percentage
-
-// Compound units
-HKUnit.count().unitDivided(by: .minute())   // Heart rate (bpm)
-HKUnit.meter().unitDivided(by: .second())   // Speed (m/s)
-
-// Prefixed units
-HKUnit.gramUnit(with: .milli)               // Milligrams
-HKUnit.literUnit(with: .deci)               // Deciliters
+import HealthKit
+
+let simple: [HKUnit] = [
+    .count(), .meter(), .mile(), .kilocalorie(), .jouleUnit(with: .kilo),
+    .gramUnit(with: .kilo), .pound(), .percent()
+]
+let beatsPerMinute = HKUnit.count().unitDivided(by: .minute())
+let metresPerSecond = HKUnit.meter().unitDivided(by: .second())
+let milligrams = HKUnit.gramUnit(with: .milli)
+let decilitres = HKUnit.literUnit(with: .deci)
 ```
 
-## Common Mistakes
-
-1. **Over-requesting data types.** Request only the read/write types the feature
-   actually uses; broad HealthKit permission sheets are an App Review risk.
-2. **Treating read authorization like write authorization.** You can check
-   `.sharingAuthorized` before saving, but read denial is privacy-protected and
-   looks like app-owned-only, empty, or partial results.
-3. **Skipping `isHealthDataAvailable()`.** Check before HealthKit access and
-   handle unavailable or restricted stores without crashing.
-4. **Using callback queries for new async code.** Prefer async descriptors for
-   one-shot reads and statistics, and keep broad queries off the main actor.
-5. **Forgetting observer completion handlers.** Always call the handler; missed
-   completions can delay or stop future background deliveries.
-6. **Assuming `.immediate` means immediate.** Background delivery is capped by
-   the system and must be tested on device.
-7. **Using cumulative stats for discrete values.** Match statistics options to
-   the data type: cumulative sums for steps/energy, discrete average/min/max for
-   heart rate, weight, and similar samples.
-
-## Review Checklist
-
-- [ ] `HKHealthStore.isHealthDataAvailable()` checked before any HealthKit access
-- [ ] Only necessary data types requested in authorization
-- [ ] `Info.plist` includes `NSHealthShareUsageDescription` and/or `NSHealthUpdateUsageDescription`
-- [ ] HealthKit capability enabled in Xcode project
-- [ ] Write authorization checked before saving; read denial handled as partial
-      or empty query results
-- [ ] Single `HKHealthStore` instance reused (not created per query)
-- [ ] Async query descriptors used instead of callback-based queries
-- [ ] Heavy queries not blocking main thread
-- [ ] Statistics options match data type (cumulative vs. discrete)
-- [ ] Background delivery paired with app-launch `HKObserverQuery` setup and
-      `completionHandler` called
-- [ ] Background delivery entitlement enabled if using `enableBackgroundDelivery`
-- [ ] Background delivery tested on device and frequency caps considered
-- [ ] Workout sessions properly ended and builder finalized
-- [ ] Workout API availability and live heart-rate sensor requirements handled
-- [ ] Write operations only for sample types the app created
+## Common mistakes
+
+- **Asking for everything.** Extra types are an App Review risk.
+- **Reading the status as if it covered reads.** `.sharingAuthorized` can be
+  checked before saving. A read denial is invisible; the app just sees its own
+  samples, or empty and partial results.
+- **Skipping `isHealthDataAvailable()`.** Handle an unavailable or restricted
+  store gracefully instead of crashing.
+- **Callback queries in new async code.** Prefer the descriptor types and keep
+  large queries off the main actor.
+- **Not calling the observer completion handler.** HealthKit delays and
+  eventually stops background deliveries.
+- **Expecting `.immediate` to be immediate.** The system caps delivery; test
+  on a device.
+- **Summing discrete values.** Match the statistics option to the type.
+
+## Review checklist
+
+- [ ] `isHealthDataAvailable()` is the first HealthKit call
+- [ ] Only the types the feature needs are requested
+- [ ] Info.plist has `NSHealthShareUsageDescription` and/or `NSHealthUpdateUsageDescription`
+- [ ] The HealthKit capability is on
+- [ ] Write authorization is checked before saving; read denial is handled as empty or partial data
+- [ ] One `HKHealthStore` is shared
+- [ ] Async descriptors are used instead of callback queries
+- [ ] Heavy queries do not run on the main thread
+- [ ] Statistics options match the type (cumulative or discrete)
+- [ ] Background delivery is paired with an `HKObserverQuery` created at launch whose `completionHandler` is always called
+- [ ] The background delivery entitlement is present when `enableBackgroundDelivery` is used
+- [ ] Background delivery was tested on a device with its frequency caps in mind
+- [ ] Workout sessions are ended and their builders finished
+- [ ] Workout API availability and the external heart-rate sensor requirement are handled
+- [ ] Deletes and edits touch only samples the app created
 
 ## References
 
-- Extended patterns (workouts, anchored queries, SwiftUI integration): [references/healthkit-patterns.md](references/healthkit-patterns.md)
-- [HealthKit framework](https://sosumi.ai/documentation/healthkit)
-- [HKHealthStore](https://sosumi.ai/documentation/healthkit/hkhealthstore)
-- [HKSampleQueryDescriptor](https://sosumi.ai/documentation/healthkit/hksamplequerydescriptor)
-- [HKStatisticsQueryDescriptor](https://sosumi.ai/documentation/healthkit/hkstatisticsquerydescriptor)
-- [HKStatisticsCollectionQueryDescriptor](https://sosumi.ai/documentation/healthkit/hkstatisticscollectionquerydescriptor)
-- [HKWorkoutSession](https://sosumi.ai/documentation/healthkit/hkworkoutsession)
-- [HKLiveWorkoutBuilder](https://sosumi.ai/documentation/healthkit/hkliveworkoutbuilder)
-- [Setting up HealthKit](https://sosumi.ai/documentation/healthkit/setting-up-healthkit)
-- [Authorizing access to health data](https://sosumi.ai/documentation/healthkit/authorizing-access-to-health-data)
-- [Configuring HealthKit access](https://sosumi.ai/documentation/xcode/configuring-healthkit-access)
+- [HealthKit patterns](references/healthkit-patterns.md) - full workout manager, watch-to-phone mirroring, platform quirks and permission changes, more on background delivery, anchored queries, predicates, chart data, SwiftUI integration, characteristics
+- [HealthKit](https://developer.apple.com/documentation/healthkit)
+- [HKHealthStore](https://developer.apple.com/documentation/healthkit/hkhealthstore)
+- [HKSampleQueryDescriptor](https://developer.apple.com/documentation/healthkit/hksamplequerydescriptor)
+- [HKStatisticsQueryDescriptor](https://developer.apple.com/documentation/healthkit/hkstatisticsquerydescriptor)
+- [HKStatisticsCollectionQueryDescriptor](https://developer.apple.com/documentation/healthkit/hkstatisticscollectionquerydescriptor)
+- [HKWorkoutSession](https://developer.apple.com/documentation/healthkit/hkworkoutsession)
+- [HKLiveWorkoutBuilder](https://developer.apple.com/documentation/healthkit/hkliveworkoutbuilder)
+- [Setting up HealthKit](https://developer.apple.com/documentation/healthkit/setting-up-healthkit)
+- [Apple guide: authorizing health data access](https://developer.apple.com/documentation/healthkit/authorizing-access-to-health-data)
+- [Configuring HealthKit access](https://developer.apple.com/documentation/xcode/configuring-healthkit-access)