@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/core-motion/SKILL.md

@@ -1,423 +1,334 @@
 ---
 name: core-motion
-description: "Access Core Motion accelerometer, gyroscope, magnetometer, device-motion, pedometer, activity-recognition, altitude, headphone motion, batched high-frequency workout motion, and water-submersion/depth data. Use when reading device sensors, counting steps, detecting walking/running/driving/cycling, tracking altitude, building motion interactions, handling AirPods head tracking, or implementing watchOS dive/depth features."
+description: "Core Motion on iOS and watchOS: accelerometer, gyroscope, magnetometer, fused device motion and reference frames, CMPedometer steps, distance and floors, activity recognition, barometric and absolute altitude, AirPods head tracking, batched high-rate workout capture, watchOS water submersion and depth. Use when building tilt controls, step counters, activity-aware features, altitude tracking or other motion interactions."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# CoreMotion
+# Core Motion
 
-Read device sensor data -- accelerometer, gyroscope, magnetometer, pedometer,
-activity recognition, altitude, headphone motion, batched motion, and submersion
-depth -- on iOS and watchOS. CoreMotion fuses raw sensor inputs into processed
-device-motion data and provides pedometer/activity APIs for fitness and
-navigation use cases. Targets Swift 6.3 / iOS 26+.
+Core Motion turns the accelerometer, gyroscope, magnetometer and barometer into
+data an app can act on. It fuses the raw sensors into a single device-motion
+stream and also ships higher-level services: a pedometer, an activity
+classifier and an altimeter. Fitness, navigation, games and accessibility
+features all build on it. Examples assume Swift 6.3 and iOS 26 or later.
 
-## Contents
+Longer SwiftUI services, batched sensors, head tracking, a step dashboard,
+activity-driven modes and dive support live in the
+[motion patterns reference](references/motion-patterns.md).
 
-- [Setup](#setup)
-- [CMMotionManager: Sensor Data](#cmmotionmanager-sensor-data)
-- [Processed Device Motion](#processed-device-motion)
-- [CMPedometer: Step and Distance Data](#cmpedometer-step-and-distance-data)
-- [CMMotionActivityManager: Activity Recognition](#cmmotionactivitymanager-activity-recognition)
-- [CMAltimeter: Altitude Data](#cmaltimeter-altitude-data)
-- [Update Intervals and Battery](#update-intervals-and-battery)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Covers: activity recognition (walking, running, driving, cycling) and
+distance and floor counts from `CMPedometer`. Not for HealthKit workout
+sessions or SensorKit research data.
 
 ## Setup
 
-### Info.plist
+### Usage string
 
-Add `NSMotionUsageDescription` to Info.plist with a user-facing string explaining
-why your app needs motion data. Without this key, the app crashes on first access.
-
-```xml
-<key>NSMotionUsageDescription</key>
-<string>This app uses motion data to track your activity.</string>
-```
+Info.plist must carry `NSMotionUsageDescription`, a sentence telling the user
+why the app reads motion. If the key is absent, the process is terminated the first
+time it touches a protected motion API.
 
 ### Authorization
 
-Use the matching manager's `authorizationStatus()` or `authorizationStatus`
-property when an API exposes one (`CMPedometer`, `CMMotionActivityManager`,
-`CMAltimeter`, headphone motion, batched sensors, and submersion). Raw
-`CMMotionManager` accelerometer/gyro/device-motion streams have no explicit
-authorization request API; still ship the usage string and handle errors from
-start/update callbacks.
+Several managers expose an authorization status: `CMPedometer`,
+`CMMotionActivityManager`, `CMAltimeter`, `CMHeadphoneMotionManager`,
+`CMBatchedSensorManager` and `CMWaterSubmersionManager`. Read it before you
+start updates. The raw `CMMotionManager` streams (accelerometer, gyroscope,
+device motion) have no request call at all; ship the usage string anyway and
+treat errors delivered to the handler as the failure signal.
 
 ```swift
 import CoreMotion
 
-let status = CMMotionActivityManager.authorizationStatus()
-switch status {
-case .notDetermined:
-    // Will prompt on first use
-    break
-case .authorized:
-    break
-case .restricted, .denied:
-    // Direct user to Settings
-    break
-@unknown default:
-    break
+enum MotionAccess {
+    case ready, willPrompt, blocked
 }
-```
-
-## CMMotionManager: Sensor Data
-
-Create exactly **one** `CMMotionManager` per app. Multiple instances degrade
-sensor update rates.
 
-```swift
-import CoreMotion
-
-let motionManager = CMMotionManager()
+func pedometerAccess() -> MotionAccess {
+    switch CMPedometer.authorizationStatus() {
+    case .authorized: return .ready
+    case .notDetermined: return .willPrompt      // system asks on first query
+    case .denied, .restricted: return .blocked   // point the user at Settings
+    @unknown default: return .blocked
+    }
+}
 ```
 
-### Accelerometer Updates
+## CMMotionManager: raw sensors
 
-```swift
-guard motionManager.isAccelerometerAvailable else { return }
+Create one `CMMotionManager` for the whole app. Extra instances compete for
+the same hardware and every one of them receives updates at a lower rate.
 
-motionManager.accelerometerUpdateInterval = 1.0 / 60.0  // 60 Hz
+### Accelerometer
 
-motionManager.startAccelerometerUpdates(to: .main) { data, error in
-    guard let acceleration = data?.acceleration else { return }
-    print("x: \(acceleration.x), y: \(acceleration.y), z: \(acceleration.z)")
+```swift
+@MainActor let sensors = CMMotionManager()
+
+@MainActor func beginShakeDetection(onShake: @escaping () -> Void) {
+    guard sensors.isAccelerometerAvailable else { return }
+    sensors.accelerometerUpdateInterval = 1.0 / 60.0
+    sensors.startAccelerometerUpdates(to: .main) { sample, error in
+        guard let a = sample?.acceleration, error == nil else { return }
+        let magnitude = (a.x * a.x + a.y * a.y + a.z * a.z).squareRoot()
+        if magnitude > 2.5 { onShake() }
+    }
 }
 
-// When done:
-motionManager.stopAccelerometerUpdates()
+@MainActor func endShakeDetection() { sensors.stopAccelerometerUpdates() }
 ```
 
-### Gyroscope Updates
+`CMMotionManager` is not `Sendable`, so Swift 6 rejects a plain global `let` of
+it ("not concurrency-safe"). The shared instance is therefore `@MainActor`, and
+so is every function that touches it; the same goes for the pedometer,
+activity and altimeter globals below. Handlers queued on `.main` run on the
+main thread either way.
 
-```swift
-guard motionManager.isGyroAvailable else { return }
-
-motionManager.gyroUpdateInterval = 1.0 / 60.0
+### Gyroscope
 
-motionManager.startGyroUpdates(to: .main) { data, error in
-    guard let rotationRate = data?.rotationRate else { return }
-    print("x: \(rotationRate.x), y: \(rotationRate.y), z: \(rotationRate.z)")
+```swift
+@MainActor func beginSpinTracking() {
+    guard sensors.isGyroAvailable else { return }
+    sensors.gyroUpdateInterval = 1.0 / 30.0
+    sensors.startGyroUpdates(to: .main) { sample, error in
+        guard let spin = sample?.rotationRate, error == nil else { return }
+        _ = spin.z   // radians per second around each axis
+    }
 }
 
-motionManager.stopGyroUpdates()
+@MainActor func endSpinTracking() { sensors.stopGyroUpdates() }
 ```
 
-### Polling Pattern (Games)
+### Polling from a game loop
 
-For games, start updates without a handler and poll the latest sample each frame:
+A game that already runs a per-frame loop can skip the handler. Call the
+start method with no arguments and read the latest value when drawing.
 
 ```swift
-motionManager.startAccelerometerUpdates()
+sensors.startAccelerometerUpdates()
 
-// In your game loop / display link:
-if let data = motionManager.accelerometerData {
-    let tilt = data.acceleration.x
-    // Move player based on tilt
+@MainActor func tick() {   // called from a display link or render loop
+    guard let latest = sensors.accelerometerData else { return }
+    applyTilt(x: latest.acceleration.x)
 }
 ```
 
-## Processed Device Motion
+## Device motion
 
-Device motion fuses accelerometer, gyroscope, and magnetometer into a single
-`CMDeviceMotion` object with attitude, user acceleration (gravity removed),
-rotation rate, and calibrated magnetic field.
+`CMDeviceMotion` blends accelerometer, gyroscope and magnetometer readings.
+Each sample carries `attitude`, `userAcceleration` (gravity already removed),
+`gravity`, `rotationRate`, a calibrated `magneticField` and `heading`, which is
+reported in degrees relative to the active reference frame.
 
-When giving device-motion guidance, show the runtime frame check in the snippet
-instead of hard-coding a corrected, magnetic-north, or true-north frame. Fall
-back to `.xArbitraryZVertical` when the preferred frame is unavailable.
+Never hard-code a reference frame. Ask
+`CMMotionManager.availableAttitudeReferenceFrames()` at runtime and fall back
+to `.xArbitraryZVertical`.
 
 ```swift
-guard motionManager.isDeviceMotionAvailable else { return }
-
-let availableFrames = CMMotionManager.availableAttitudeReferenceFrames()
-let frame: CMAttitudeReferenceFrame = availableFrames.contains(.xArbitraryCorrectedZVertical)
-    ? .xArbitraryCorrectedZVertical
-    : .xArbitraryZVertical
-
-motionManager.deviceMotionUpdateInterval = 1.0 / 60.0
-
-motionManager.startDeviceMotionUpdates(
-    using: frame,
-    to: .main
-) { motion, error in
-    guard let motion else { return }
-
-    let attitude = motion.attitude       // roll, pitch, yaw
-    let userAccel = motion.userAcceleration
-    let gravity = motion.gravity
-    let heading = motion.heading         // degrees relative to the current frame
-
-    print("Pitch: \(attitude.pitch), Roll: \(attitude.roll)")
+@MainActor func beginOrientationTracking() {
+    guard sensors.isDeviceMotionAvailable else { return }
+    let offered = CMMotionManager.availableAttitudeReferenceFrames()
+    let frame: CMAttitudeReferenceFrame =
+        offered.contains(.xArbitraryCorrectedZVertical)
+        ? .xArbitraryCorrectedZVertical
+        : .xArbitraryZVertical
+
+    sensors.deviceMotionUpdateInterval = 1.0 / 30.0
+    sensors.startDeviceMotionUpdates(using: frame, to: .main) { reading, failure in
+        guard let reading, failure == nil else { return }
+        let tilt = reading.attitude          // roll, pitch, yaw in radians
+        let push = reading.userAcceleration  // in g, gravity removed
+        let down = reading.gravity
+        let degrees = reading.heading
+        _ = (tilt.roll, push.z, down.y, degrees)
+    }
 }
 
-motionManager.stopDeviceMotionUpdates()
+@MainActor func endOrientationTracking() { sensors.stopDeviceMotionUpdates() }
 ```
 
-### Attitude Reference Frames
+### Reference frames
 
-For simple tilt controls, use `.xArbitraryZVertical` or
-`.xArbitraryCorrectedZVertical`; they avoid magnetometer/location dependencies.
-Before requesting corrected, magnetic-north, or true-north frames, call
-`CMMotionManager.availableAttitudeReferenceFrames()` and fall back to an
-available frame.
+| Frame | X axis | Needs | Good for |
+|---|---|---|---|
+| `.xArbitraryZVertical` | wherever the device pointed at start; the default | nothing extra | most games, tilt |
+| `.xArbitraryCorrectedZVertical` | same, with gyro drift corrected over time | nothing extra | longer tilt sessions |
+| `.xMagneticNorthZVertical` | magnetic north | magnetometer | compass-like UI |
+| `.xTrueNorthZVertical` | true north | magnetometer and location | geographic alignment |
 
-| Frame | Use Case |
-|---|---|
-| `.xArbitraryZVertical` | Default. Z is vertical, X arbitrary at start. Most games. |
-| `.xArbitraryCorrectedZVertical` | Same as above, corrected for gyro drift over time. |
-| `.xMagneticNorthZVertical` | X points to magnetic north. Requires magnetometer. |
-| `.xTrueNorthZVertical` | X points to true north. Requires magnetometer + location. |
+For plain tilt, pick one of the two arbitrary frames: they do not depend on the
+magnetometer or on location. Before asking for a north frame, confirm
+`availableAttitudeReferenceFrames().contains(...)` includes it.
 
-Check available frames before use:
+## CMPedometer
 
-```swift
-let available = CMMotionManager.availableAttitudeReferenceFrames()
-if available.contains(.xTrueNorthZVertical) {
-    // Safe to use true north
-}
-```
-
-## CMPedometer: Step and Distance Data
-
-`CMPedometer` provides step counts, distance, pace, cadence, and floor counts.
+The pedometer reports step count, distance, pace, cadence and floors climbed
+or descended.
 
 ```swift
-let pedometer = CMPedometer()
-
-guard CMPedometer.isStepCountingAvailable() else { return }
-
-// Historical query
-pedometer.queryPedometerData(
-    from: Calendar.current.startOfDay(for: Date()),
-    to: Date()
-) { data, error in
-    guard let data else { return }
-    print("Steps today: \(data.numberOfSteps)")
-    print("Distance: \(data.distance?.doubleValue ?? 0) meters")
-    print("Floors up: \(data.floorsAscended?.intValue ?? 0)")
+@MainActor let stepCounter = CMPedometer()
+
+@MainActor func loadTodaysWalk() {
+    guard CMPedometer.isStepCountingAvailable() else { return }
+    let midnight = Calendar.current.startOfDay(for: .now)
+    stepCounter.queryPedometerData(from: midnight, to: .now) { summary, error in
+        guard let summary, error == nil else { return }
+        let steps = summary.numberOfSteps.intValue
+        let meters = summary.distance?.doubleValue ?? 0
+        let climbed = summary.floorsAscended?.intValue ?? 0
+        _ = (steps, meters, climbed)
+    }
 }
 
-// Live updates
-pedometer.startUpdates(from: Date()) { data, error in
-    guard let data else { return }
-    print("Steps: \(data.numberOfSteps)")
+@MainActor func followLiveSteps(since start: Date) {
+    stepCounter.startUpdates(from: start) { summary, _ in
+        _ = summary?.numberOfSteps
+    }
 }
 
-// Stop when done
-pedometer.stopUpdates()
+@MainActor func stopLiveSteps() { stepCounter.stopUpdates() }
 ```
 
-### Availability Checks
+Each metric has its own capability check:
 
-| Method | What It Checks |
-|---|---|
-| `isStepCountingAvailable()` | Step counter hardware |
-| `isDistanceAvailable()` | Distance estimation |
-| `isFloorCountingAvailable()` | Barometric altimeter for floors |
-| `isPaceAvailable()` | Pace data |
-| `isCadenceAvailable()` | Cadence data |
+- `isStepCountingAvailable()` - step hardware present
+- `isDistanceAvailable()` - distance estimates
+- `isFloorCountingAvailable()` - floors, which need a barometer
+- `isPaceAvailable()` - pace
+- `isCadenceAvailable()` - cadence
 
-## CMMotionActivityManager: Activity Recognition
+## CMMotionActivityManager
 
-Detects whether the user is stationary, walking, running, cycling, or in a vehicle.
+The classifier reports stationary, walking, running, cycling and automotive
+states.
 
 ```swift
-let activityManager = CMMotionActivityManager()
-
-guard CMMotionActivityManager.isActivityAvailable() else { return }
-
-// Live activity updates
-activityManager.startActivityUpdates(to: .main) { activity in
-    guard let activity else { return }
-
-    if activity.walking {
-        print("Walking (confidence: \(activity.confidence.rawValue))")
-    } else if activity.running {
-        print("Running")
-    } else if activity.automotive {
-        print("In vehicle")
-    } else if activity.cycling {
-        print("Cycling")
-    } else if activity.stationary {
-        print("Stationary")
+@MainActor let classifier = CMMotionActivityManager()
+
+@MainActor func watchMovement() {
+    guard CMMotionActivityManager.isActivityAvailable() else { return }
+    classifier.startActivityUpdates(to: .main) { activity in
+        guard let activity else { return }
+        let flags = (activity.walking, activity.running, activity.cycling,
+                     activity.automotive, activity.stationary)
+        let certainty = activity.confidence.rawValue   // 0 low, 1 medium, 2 high
+        _ = (flags, certainty)
     }
 }
 
-activityManager.stopActivityUpdates()
+@MainActor func stopWatchingMovement() { classifier.stopActivityUpdates() }
 ```
 
-### Historical Activity Query
+### Looking back
 
 ```swift
-let yesterday = Calendar.current.date(byAdding: .day, value: -1, to: Date())!
-
-activityManager.queryActivityStarting(
-    from: yesterday,
-    to: Date(),
-    to: .main
-) { activities, error in
-    guard let activities else { return }
-    for activity in activities {
-        print("\(activity.startDate): walking=\(activity.walking)")
+@MainActor func lastDayOfActivity() {
+    let end = Date.now
+    let start = end.addingTimeInterval(-24 * 60 * 60)
+    classifier.queryActivityStarting(from: start, to: end, to: .main) { entries, _ in
+        for entry in entries ?? [] { _ = entry.startDate }
     }
 }
 ```
 
-## CMAltimeter: Altitude Data
-
-Altimeter access is covered by `NSMotionUsageDescription`; handle denied motion
-access through unavailable data and update-handler errors.
+## CMAltimeter
 
-```swift
-let altimeter = CMAltimeter()
+The same `NSMotionUsageDescription` covers the altimeter. When the user denies
+motion access, altitude simply stops being available and the handlers receive
+errors.
 
-guard CMAltimeter.isRelativeAltitudeAvailable() else { return }
-
-altimeter.startRelativeAltitudeUpdates(to: .main) { data, error in
-    guard let data else { return }
-    print("Relative altitude: \(data.relativeAltitude) meters")
-    print("Pressure: \(data.pressure) kPa")
-}
-
-altimeter.stopRelativeAltitudeUpdates()
-```
-
-Absolute altitude is altitude relative to sea level, not GPS-based altitude.
-First check availability. Absolute altitude is available only on supported
-hardware such as iPhone 12 or later and Apple Watch Series 6, Apple Watch SE, or
-later.
+### Relative altitude
 
 ```swift
-guard CMAltimeter.isAbsoluteAltitudeAvailable() else { return }
-
-altimeter.startAbsoluteAltitudeUpdates(to: .main) { data, error in
-    guard let data else { return }
-    print("Altitude: \(data.altitude)m, accuracy: \(data.accuracy)m")
+@MainActor let barometer = CMAltimeter()
+
+@MainActor func trackClimb() {
+    guard CMAltimeter.isRelativeAltitudeAvailable() else { return }
+    barometer.startRelativeAltitudeUpdates(to: .main) { reading, error in
+        guard let reading, error == nil else { return }
+        let gainedMeters = reading.relativeAltitude.doubleValue
+        let kilopascals = reading.pressure.doubleValue
+        _ = (gainedMeters, kilopascals)
+    }
 }
 
-altimeter.stopAbsoluteAltitudeUpdates()
+@MainActor func stopClimb() { barometer.stopRelativeAltitudeUpdates() }
 ```
 
-## Update Intervals and Battery
-
-| Interval | Hz | Use Case | Battery Impact |
-|---|---|---|---|
-| `1.0 / 10.0` | 10 | UI orientation | Low |
-| `1.0 / 30.0` | 30 | Casual games | Moderate |
-| `1.0 / 60.0` | 60 | Action games | High |
-| `1.0 / 100.0` | 100 | Max rate (iPhone) | Very High |
-
-Use the lowest frequency that meets your needs. Do not assume a fixed maximum
-sample rate across devices. For high-frequency workout motion, use
-`CMBatchedSensorManager` where supported and read its reported
-`accelerometerDataFrequency` or `deviceMotionDataFrequency` instead of assigning
-those read-only properties.
+### Absolute altitude
 
-## Common Mistakes
-
-### DON'T: Create multiple CMMotionManager instances
-
-```swift
-// WRONG -- degrades update rates for all instances
-class ViewA { let motion = CMMotionManager() }
-class ViewB { let motion = CMMotionManager() }
-
-// CORRECT -- single instance, shared across the app
-@Observable
-final class MotionService {
-    static let shared = MotionService()
-    let manager = CMMotionManager()
-}
-```
-
-### DON'T: Skip sensor availability checks
+Absolute altitude is height above sea level estimated by the system, not a GPS
+fix. Supported hardware starts at iPhone 12 on the phone side; on the wrist it
+starts at Apple Watch Series 6 and Apple Watch SE. Always gate on `isAbsoluteAltitudeAvailable()`.
 
 ```swift
-// WRONG -- crashes on devices without gyroscope
-motionManager.startGyroUpdates(to: .main) { data, _ in }
-
-// CORRECT -- check first
-guard motionManager.isGyroAvailable else {
-    showUnsupportedMessage()
-    return
-}
-motionManager.startGyroUpdates(to: .main) { data, _ in }
-```
-
-### DON'T: Forget to stop updates
-
-```swift
-// WRONG -- updates keep running, draining battery
-class MotionVC: UIViewController {
-    override func viewDidAppear(_ animated: Bool) {
-        super.viewDidAppear(animated)
-        motionManager.startAccelerometerUpdates(to: .main) { _, _ in }
+@MainActor func trackElevation() {
+    guard CMAltimeter.isAbsoluteAltitudeAvailable() else { return }
+    barometer.startAbsoluteAltitudeUpdates(to: .main) { reading, error in
+        guard let reading, error == nil else { return }
+        _ = (reading.altitude, reading.accuracy)   // both in meters
     }
-    // Missing viewDidDisappear stop!
 }
 
-// CORRECT -- stop in the counterpart lifecycle method
-override func viewDidDisappear(_ animated: Bool) {
-    super.viewDidDisappear(animated)
-    motionManager.stopAccelerometerUpdates()
-}
-```
-
-### DON'T: Use unnecessarily high update rates
-
-```swift
-// WRONG -- 100 Hz for a compass display
-motionManager.deviceMotionUpdateInterval = 1.0 / 100.0
-
-// CORRECT -- 10 Hz is more than enough for a compass
-motionManager.deviceMotionUpdateInterval = 1.0 / 10.0
-```
-
-### DON'T: Assume all CMMotionActivity properties are mutually exclusive
-
-```swift
-// WRONG -- checking only one property
-if activity.walking { handleWalking() }
-
-// CORRECT -- multiple can be true simultaneously; check confidence
-if activity.walking && activity.confidence == .high {
-    handleWalking()
-} else if activity.automotive && activity.confidence != .low {
-    handleDriving()
-}
+@MainActor func stopElevation() { barometer.stopAbsoluteAltitudeUpdates() }
 ```
 
-## Review Checklist
+## Update rates and battery
 
-- [ ] `NSMotionUsageDescription` present in Info.plist with a clear explanation
-- [ ] Single `CMMotionManager` instance shared across the app
-- [ ] Sensor availability checked before starting updates (`isAccelerometerAvailable`, etc.)
-- [ ] Authorization status checked before pedometer/activity APIs
-- [ ] Update interval set to the lowest acceptable frequency
-- [ ] All `start*Updates` calls have matching `stop*Updates` in lifecycle counterparts
-- [ ] Handlers dispatched to appropriate queues (not blocking main for heavy processing)
-- [ ] `CMMotionActivity.confidence` checked before acting on activity type
-- [ ] Error parameters checked in update handlers
-- [ ] Device-motion snippets call `CMMotionManager.availableAttitudeReferenceFrames()` before requesting a specific attitude frame
-- [ ] Attitude reference frame chosen based on actual need (not defaulting to true north unnecessarily)
+| Use case | Frequency | Energy impact | Interval to set |
+|---|---|---|---|
+| UI that follows orientation | 10 Hz | low | `1.0 / 10.0` |
+| Casual game | 30 Hz | moderate | `1.0 / 30.0` |
+| Fast action game | 60 Hz | high | `1.0 / 60.0` |
+| Fastest iPhone sampling | 100 Hz | very high | `1.0 / 100.0` |
+
+Pick the slowest rate the feature tolerates. The ceiling differs from one
+device model to the next, so no code path should rely on a fixed maximum. For high-frequency workout
+analysis, prefer `CMBatchedSensorManager` where it is supported, and read its
+`accelerometerDataFrequency` or `deviceMotionDataFrequency`. Those two
+properties are read-only; there is nothing to assign.
+
+## Common mistakes
+
+- **Several `CMMotionManager` objects.** Rates drop for all of them. Wrap one
+  manager in a shared `@Observable` service exposed as `static let shared`.
+- **No availability guard.** Starting gyroscope updates without checking
+  `isGyroAvailable` can crash on hardware that lacks one. Guard first and tell
+  the user the feature is unsupported.
+- **Never stopping.** Sensors keep running and drain the battery. Pair every
+  start with a stop in the matching lifecycle callback, for example
+  `viewDidAppear` with `viewDidDisappear`.
+- **Oversampling.** A compass needle does not need 100 Hz; 10 Hz is plenty.
+- **Treating activity flags as exclusive.** Several can be true together.
+  Combine them with `confidence`, for example act on `walking` only at `.high`,
+  and on `automotive` only when confidence is not `.low`.
+
+## Review checklist
+
+- [ ] Info.plist has a clear `NSMotionUsageDescription`
+- [ ] The app owns exactly one shared `CMMotionManager`
+- [ ] Availability (`isAccelerometerAvailable` and friends) is checked before any start call
+- [ ] Authorization is read before pedometer and activity APIs are used
+- [ ] The update interval is the lowest that still works
+- [ ] Every `start*Updates` has a `stop*Updates` in the opposite lifecycle event
+- [ ] Handlers run on a suitable queue and heavy processing stays off the main thread
+- [ ] `CMMotionActivity.confidence` is checked before the app reacts
+- [ ] Handler `error` parameters are inspected
+- [ ] Device-motion code calls `availableAttitudeReferenceFrames()` before choosing a frame
+- [ ] The frame matches the need; true north is never the default
 
 ## References
 
-- Extended patterns (SwiftUI integration, batched sensor manager, headphone motion, water submersion): [references/motion-patterns.md](references/motion-patterns.md)
-- [CoreMotion framework](https://sosumi.ai/documentation/coremotion)
-- [CMMotionManager](https://sosumi.ai/documentation/coremotion/cmmotionmanager)
-- [CMPedometer](https://sosumi.ai/documentation/coremotion/cmpedometer)
-- [CMMotionActivityManager](https://sosumi.ai/documentation/coremotion/cmmotionactivitymanager)
-- [CMDeviceMotion](https://sosumi.ai/documentation/coremotion/cmdevicemotion)
-- [CMAltimeter](https://sosumi.ai/documentation/coremotion/cmaltimeter)
-- [CMAbsoluteAltitudeData](https://sosumi.ai/documentation/coremotion/cmabsolutealtitudedata)
-- [CMBatchedSensorManager](https://sosumi.ai/documentation/coremotion/cmbatchedsensormanager)
-- [CMHeadphoneMotionManager](https://sosumi.ai/documentation/coremotion/cmheadphonemotionmanager)
-- [CMWaterSubmersionManager](https://sosumi.ai/documentation/coremotion/cmwatersubmersionmanager)
-- [Accessing submersion data](https://sosumi.ai/documentation/coremotion/accessing-submersion-data)
-- [Getting processed device-motion data](https://sosumi.ai/documentation/coremotion/getting-processed-device-motion-data)
+- [Motion patterns](references/motion-patterns.md) - SwiftUI services, batched sensors, headphone motion, pedometer dashboard, activity modes, water submersion
+- [Core Motion](https://developer.apple.com/documentation/coremotion)
+- [CMMotionManager](https://developer.apple.com/documentation/coremotion/cmmotionmanager)
+- [CMPedometer](https://developer.apple.com/documentation/coremotion/cmpedometer)
+- [CMMotionActivityManager](https://developer.apple.com/documentation/coremotion/cmmotionactivitymanager)
+- [CMDeviceMotion](https://developer.apple.com/documentation/coremotion/cmdevicemotion)
+- [CMAltimeter](https://developer.apple.com/documentation/coremotion/cmaltimeter)
+- [CMAbsoluteAltitudeData](https://developer.apple.com/documentation/coremotion/cmabsolutealtitudedata)
+- [CMBatchedSensorManager](https://developer.apple.com/documentation/coremotion/cmbatchedsensormanager)
+- [CMHeadphoneMotionManager](https://developer.apple.com/documentation/coremotion/cmheadphonemotionmanager)
+- [CMWaterSubmersionManager](https://developer.apple.com/documentation/coremotion/cmwatersubmersionmanager)
+- [Accessing submersion data](https://developer.apple.com/documentation/coremotion/accessing-submersion-data)
+- [Getting processed device-motion data](https://developer.apple.com/documentation/coremotion/getting-processed-device-motion-data)