@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/metrickit-diagnostics/SKILL.md

@@ -1,438 +1,255 @@
 ---
 name: metrickit-diagnostics
-description: "Collect and analyze on-device performance metrics and crash diagnostics using MetricKit. Use when setting up MXMetricManager, handling MXMetricPayload or MXDiagnosticPayload, processing crash/hang/disk-write diagnostics via MXCallStackTree, adding custom signpost metrics, correcting mxSignpost or extended launch measurement code, or uploading telemetry to an analytics backend."
+description: "MetricKit field telemetry from shipping apps: MXMetricManager subscribers, MXMetricPayload and MXDiagnosticPayload, crash, hang and disk-write call stacks in MXCallStackTree, custom mxSignpost metrics, extended launch measurement, exporting payloads to an analytics backend. Use when setting up MetricKit, fixing mxSignpost or extended-launch code, or uploading field diagnostics."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # MetricKit
 
-Collect aggregated performance metrics and crash diagnostics from production
-devices using MetricKit. The framework delivers daily metric payloads (CPU,
-memory, launch time, hang rate, animation hitches, network usage) and
-diagnostic payloads (crashes, hangs, disk-write exceptions) with call-stack
-trees for triage.
-
-## Contents
-
-- [Subscriber Setup](#subscriber-setup)
-- [Receiving Metric Payloads](#receiving-metric-payloads)
-- [Receiving Diagnostic Payloads](#receiving-diagnostic-payloads)
-- [Key Metrics](#key-metrics)
-- [Call Stack Trees](#call-stack-trees)
-- [Custom Signpost Metrics](#custom-signpost-metrics)
-- [Exporting and Uploading Payloads](#exporting-and-uploading-payloads)
-- [Extended Launch Measurement](#extended-launch-measurement)
-- [Xcode Organizer Integration](#xcode-organizer-integration)
-- [Scope Boundaries](#scope-boundaries)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Subscriber Setup
-
-Register a subscriber as early as possible  -  ideally in
-`application(_:didFinishLaunchingWithOptions:)` or `App.init`. MetricKit
-starts accumulating reports after the first access to `MXMetricManager.shared`.
-When backfilling, state precisely that `pastPayloads` and
-`pastDiagnosticPayloads` return reports generated since the last allocation of
-the shared manager instance.
+MetricKit reports how the app behaves on real devices. Two kinds of payload
+arrive:
+
+- **Metric payloads**, aggregated daily: CPU, memory, launch and resume
+  time, hang rate, scroll hitches, network use and more.
+- **Diagnostic payloads**: crashes, hangs, CPU exceptions and disk-write
+  exceptions, each with a call-stack tree.
+
+## Registering a subscriber
+
+MetricKit starts gathering data the first time the app touches
+`MXMetricManager.shared`, so register as early as launch allows:
+`application(_:didFinishLaunchingWithOptions:)` in UIKit, `App.init` in
+SwiftUI.
+
+`pastPayloads` and `pastDiagnosticPayloads` hold the reports produced since
+the shared manager instance was last allocated. Use exactly that wording when
+you describe a backfill; they are not "everything MetricKit ever collected".
 
 ```swift
 import MetricKit
 
-final class MetricsSubscriber: NSObject, MXMetricManagerSubscriber {
-    static let shared = MetricsSubscriber()
+final class FieldTelemetry: NSObject, MXMetricManagerSubscriber, Sendable {
+    static let shared = FieldTelemetry()
 
-    func subscribe() {
+    func start() {
         let manager = MXMetricManager.shared
         manager.add(self)
-
-        // Reports generated since the last allocation of the shared manager.
-        processMetricPayloads(manager.pastPayloads)
-        processDiagnosticPayloads(manager.pastDiagnosticPayloads)
+        store(manager.pastPayloads)
+        store(manager.pastDiagnosticPayloads)
     }
 
-    func unsubscribe() {
+    func stop() {
         MXMetricManager.shared.remove(self)
     }
 
     func didReceive(_ payloads: [MXMetricPayload]) {
-        processMetricPayloads(payloads)
+        store(payloads)
     }
 
     func didReceive(_ payloads: [MXDiagnosticPayload]) {
-        processDiagnosticPayloads(payloads)
+        store(payloads)
     }
+
+    private func store(_ payloads: [MXMetricPayload]) { /* see Exporting */ }
+    private func store(_ payloads: [MXDiagnosticPayload]) { /* see Exporting */ }
 }
 ```
 
-### UIKit Registration
-
 ```swift
-func application(
-    _ application: UIApplication,
-    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
-) -> Bool {
-    MetricsSubscriber.shared.subscribe()
+// UIKit
+func application(_ application: UIApplication,
+                 didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+    FieldTelemetry.shared.start()
     return true
 }
-```
-
-### SwiftUI Registration
 
-```swift
+// SwiftUI
 @main
-struct MyApp: App {
-    init() {
-        MetricsSubscriber.shared.subscribe()
-    }
+struct TrailheadApp: App {
+    init() { FieldTelemetry.shared.start() }
     var body: some Scene {
-        WindowGroup { ContentView() }
+        WindowGroup { RootView() }
     }
 }
 ```
 
-## Receiving Metric Payloads
+## Metric payloads
 
-`MXMetricPayload` arrives approximately once per 24 hours containing
-aggregated metrics. The array may contain multiple payloads if prior
-deliveries were missed.
+An `MXMetricPayload` shows up roughly once every 24 hours. If earlier
+deliveries were missed, one callback can carry several. Each payload has
+`timeStampBegin`, `timeStampEnd` and `latestApplicationVersion`. Save
+`jsonRepresentation()` first, then queue any processing.
 
-```swift
-func didReceive(_ payloads: [MXMetricPayload]) {
-    for payload in payloads {
-        let begin = payload.timeStampBegin
-        let end = payload.timeStampEnd
-        let version = payload.latestApplicationVersion
-
-        // Persist raw JSON before processing
-        let jsonData = payload.jsonRepresentation()
-        persistPayload(jsonData, from: begin, to: end)
-
-        enqueueMetricProcessing(jsonData)
-    }
-}
-```
+Available since macOS 10.15, iOS and iPadOS 13, Mac Catalyst 13.1 and
+visionOS 1.
 
-**Availability**: `MXMetricPayload`  -  iOS 13.0+, iPadOS 13.0+,
-Mac Catalyst 13.1+, macOS 10.15+, visionOS 1.0+
+## Diagnostic payloads
 
-## Receiving Diagnostic Payloads
-
-`MXDiagnosticPayload` delivers crash, hang, CPU exception, disk-write, and
-app-launch diagnostics where supported. On iOS 15+ and macOS 12+, supported
-diagnostics can arrive as soon as available rather than bundled with the daily
-report.
+`MXDiagnosticPayload` groups several diagnostic kinds: crashes, hangs,
+CPU exceptions, excessive disk writes and, on platforms that support them,
+slow app launches. Since iOS 15 and
+macOS 12 supported diagnostics are delivered as soon as they are available
+instead of waiting for the daily report.
 
 ```swift
 func didReceive(_ payloads: [MXDiagnosticPayload]) {
     for payload in payloads {
-        let jsonData = payload.jsonRepresentation()
-        persistPayload(jsonData)
-        enqueueDiagnosticProcessing(jsonData)
+        persist(payload.jsonRepresentation())       // durable first
     }
+    Task.detached(priority: .utility) { await DiagnosticsQueue.shared.drain() }
 }
-```
-
-In the background processor, inspect the typed diagnostic arrays after the raw
-payload is durable:
 
-```swift
-func processDiagnosticPayload(_ payload: MXDiagnosticPayload) {
-    if let crashes = payload.crashDiagnostics {
-        for crash in crashes {
-            handleCrash(crash)
-        }
-    }
-    if let hangs = payload.hangDiagnostics {
-        for hang in hangs {
-            handleHang(hang)
-        }
-    }
-    if let diskWrites = payload.diskWriteExceptionDiagnostics {
-        for diskWrite in diskWrites {
-            handleDiskWrite(diskWrite)
-        }
-    }
-    if let cpuExceptions = payload.cpuExceptionDiagnostics {
-        for cpuException in cpuExceptions {
-            handleCPUException(cpuException)
-        }
-    }
-    #if os(iOS) || targetEnvironment(macCatalyst) || os(visionOS)
-    if #available(iOS 16.0, macCatalyst 16.0, visionOS 1.0, *),
-       let launchDiagnostics = payload.appLaunchDiagnostics {
-        for launchDiagnostic in launchDiagnostics {
-            handleSlowLaunch(launchDiagnostic)
-        }
+func summarize(_ payload: MXDiagnosticPayload) -> [String: Int] {
+    var counts: [String: Int] = [
+        "crash": payload.crashDiagnostics?.count ?? 0,
+        "hang": payload.hangDiagnostics?.count ?? 0,
+        "diskWrite": payload.diskWriteExceptionDiagnostics?.count ?? 0,
+        "cpu": payload.cpuExceptionDiagnostics?.count ?? 0
+    ]
+    #if os(iOS) || os(visionOS) || targetEnvironment(macCatalyst)
+    if #available(iOS 16, macCatalyst 16, visionOS 1, *) {
+        counts["launch"] = payload.appLaunchDiagnostics?.count ?? 0
     }
     #endif
+    return counts
 }
 ```
 
-**Availability**: `MXDiagnosticPayload`  -  iOS 14.0+, iPadOS 14.0+,
-Mac Catalyst 14.0+, macOS 12.0+, visionOS 1.0+. `appLaunchDiagnostics`
-requires iOS 16.0+, iPadOS 16.0+, Mac Catalyst 16.0+, or visionOS 1.0+.
+The callback only persists and schedules; inspecting the typed arrays
+happens later, in the background worker.
 
-## Key Metrics
+| Type | iOS / iPadOS | Mac Catalyst | macOS | visionOS |
+|---|---|---|---|---|
+| `MXDiagnosticPayload` | 14 | 14 | 12 | 1 |
+| `appLaunchDiagnostics` | 16 | 16 | not available | 1 |
+| `MXCallStackTree` | 14 | 14 | 12 | 1 |
 
-### Launch Time  -  MXAppLaunchMetric
+## Metrics worth reading
 
-```swift
-if let launch = payload.applicationLaunchMetrics {
-    let firstDraw = launch.histogrammedTimeToFirstDraw
-    let optimized = launch.histogrammedOptimizedTimeToFirstDraw
-    let resume = launch.histogrammedApplicationResumeTime
-    let extended = launch.histogrammedExtendedLaunch
-}
-```
+| Payload property | Type | Useful values |
+|---|---|---|
+| `applicationLaunchMetrics` | `MXAppLaunchMetric` | `histogrammedTimeToFirstDraw`, `histogrammedOptimizedTimeToFirstDraw`, `histogrammedApplicationResumeTime`, `histogrammedExtendedLaunch` |
+| `applicationTimeMetrics` | `MXAppRunTimeMetric` | `cumulativeForegroundTime`, `cumulativeBackgroundTime`, `cumulativeBackgroundAudioTime`, `cumulativeBackgroundLocationTime` (all `Measurement<UnitDuration>`) |
+| `cpuMetrics` | `MXCPUMetric` | `cumulativeCPUTime` (duration) |
+| `memoryMetrics` | `MXMemoryMetric` | `peakMemoryUsage` (`UnitInformationStorage`) |
+| `applicationResponsivenessMetrics` | `MXAppResponsivenessMetric` | `histogrammedApplicationHangTime` |
+| `animationMetrics` | `MXAnimationMetric` | `scrollHitchTimeRatio` |
+| `networkTransferMetrics` | `MXNetworkTransferMetric` | `cumulativeWifiUpload`, `cumulativeWifiDownload`, `cumulativeCellularUpload`, `cumulativeCellularDownload` (`UnitInformationStorage`) |
+| `applicationExitMetrics` | `MXAppExitMetric` | `foregroundExitData`, `backgroundExitData`: normal, abnormal, watchdog, memory-limit and other exit counts |
 
-### Run Time  -  MXAppRunTimeMetric
+## Call-stack trees
 
-```swift
-if let runTime = payload.applicationTimeMetrics {
-    let fg = runTime.cumulativeForegroundTime    // Measurement<UnitDuration>
-    let bg = runTime.cumulativeBackgroundTime
-    let bgAudio = runTime.cumulativeBackgroundAudioTime
-    let bgLocation = runTime.cumulativeBackgroundLocationTime
-}
-```
+Every diagnostic carries an `MXCallStackTree`. Its `jsonRepresentation()`
+lists the frames; symbolicate them with `atos`, or upload the JSON together
+with the build's dSYMs to your crash service.
 
-### CPU, Memory, and Responsiveness
+## Custom signpost metrics
 
-```swift
-if let cpu = payload.cpuMetrics {
-    let cpuTime = cpu.cumulativeCPUTime              // Measurement<UnitDuration>
-}
-if let memory = payload.memoryMetrics {
-    let peakMemory = memory.peakMemoryUsage           // Measurement<UnitInformationStorage>
-}
-if let responsiveness = payload.applicationResponsivenessMetrics {
-    let hangTime = responsiveness.histogrammedApplicationHangTime
-}
-if let animation = payload.animationMetrics {
-    let scrollHitchRate = animation.scrollHitchTimeRatio  // Measurement<Unit>
-}
-```
-
-### Network and Cellular
+Emit `mxSignpost` on a log handle from `MXMetricManager.makeLogHandle(category:)`.
+Leave `dso`, `signpostID` and `format` at their defaults. The basic pattern
+needs no `OSSignpostID`; create one only to tell apart intervals with the
+same name that overlap.
 
 ```swift
-if let network = payload.networkTransferMetrics {
-    let wifiUp = network.cumulativeWifiUpload          // Measurement<UnitInformationStorage>
-    let wifiDown = network.cumulativeWifiDownload
-    let cellUp = network.cumulativeCellularUpload
-    let cellDown = network.cumulativeCellularDownload
-}
-```
+import MetricKit
 
-### App Exit Metrics
+let checkoutLog = MXMetricManager.makeLogHandle(category: "Checkout")
 
-```swift
-if let exits = payload.applicationExitMetrics {
-    let fg = exits.foregroundExitData
-    let bg = exits.backgroundExitData
-    // Inspect normal, abnormal, watchdog, memory, etc.
+func placeOrder(_ cart: Cart) async throws {
+    mxSignpost(.begin, log: checkoutLog, name: "PlaceOrder")
+    defer { mxSignpost(.end, log: checkoutLog, name: "PlaceOrder") }
+    try await orderService.submit(cart)
 }
 ```
 
-## Call Stack Trees
-
-`MXCallStackTree` is attached to each diagnostic. Use `jsonRepresentation()` to extract frame data, then symbolicate with `atos` or by uploading dSYMs to your analytics service.
+The aggregated numbers come back in the daily payload under
+`MXMetricPayload.signpostMetrics`. Say so explicitly when reviewing or fixing
+signpost code, because people often look for them in diagnostics.
 
-See [references/metrickit-patterns.md](references/metrickit-patterns.md) for crash/hang handling code and JSON structure details.
+## Exporting
 
-**Availability**: `MXCallStackTree`  -  iOS 14.0+, iPadOS 14.0+,
-Mac Catalyst 14.0+, macOS 12.0+, visionOS 1.0+
+Both payload classes provide `jsonRepresentation()`. Write the raw JSON to
+disk before any parsing or upload, and read the past-payload properties at
+launch in case callbacks were missed. Upload code is in
+[MetricKit patterns](references/metrickit-patterns.md).
 
-## Custom Signpost Metrics
+## Extended launch measurement
 
-Use `mxSignpost` with a MetricKit log handle to capture custom performance
-intervals. Leave the advanced `dso`, `signpostID`, and `format` parameters at
-their documented defaults. Custom metrics appear in the daily `MXMetricPayload`
-under `signpostMetrics`; call that out when reviewing custom MetricKit
-instrumentation. When correcting custom signpost code, explicitly name
-`MXMetricPayload.signpostMetrics` so the caller knows where the data lands.
-Do not allocate or pass an `OSSignpostID` for the basic MetricKit pattern; use
-the defaulted `mxSignpost(.begin/.end, log:name:)` calls unless there is a
-specific overlapping-interval reason to do otherwise.
+Lets launch time include setup that happens after the first frame, such as
+opening a database. Available on iOS and iPadOS 16+, Mac Catalyst 16+,
+macOS 13+ and visionOS 1+. Both calls are throwing **type** methods on
+`MXMetricManager`, not methods on the shared instance.
 
 ```swift
-let metricLog = MXMetricManager.makeLogHandle(category: "Networking")
-mxSignpost(.begin, log: metricLog, name: "DataFetch")
-defer { mxSignpost(.end, log: metricLog, name: "DataFetch") }
-
-let data = try await fetchData()
-```
+let warmCatalog = MXLaunchTaskID("com.example.trailhead.catalog")
 
-See [references/metrickit-patterns.md](references/metrickit-patterns.md) for signpost emission patterns and reading custom metrics from payloads.
-
-## Exporting and Uploading Payloads
-
-Both payload types provide `jsonRepresentation()` for serialization. Always
-persist raw JSON to disk before processing. Use `pastPayloads` and
-`pastDiagnosticPayloads` on launch to retrieve reports generated since the last
-allocation of the shared manager instance.
-
-See [references/metrickit-patterns.md](references/metrickit-patterns.md) for export code and past payload retrieval.
-
-## Extended Launch Measurement
-
-Track post-first-draw setup work as part of the launch metric on iOS 16+,
-iPadOS 16+, Mac Catalyst 16+, macOS 13+, and visionOS 1+:
-
-```swift
-let taskID = MXLaunchTaskID("com.example.app.loadDatabase")
-try MXMetricManager.extendLaunchMeasurement(forTaskID: taskID)
-defer { try? MXMetricManager.finishExtendedLaunchMeasurement(forTaskID: taskID) }
-restoreCachedState()
-```
-
-When correcting extended launch code, include the whole operational contract:
-availability is iOS/iPadOS/Mac Catalyst 16+, macOS 13+, and visionOS 1+; call
-the throwing `MXMetricManager` type methods on the main thread; start the first
-task before the first scene becomes active; keep task windows overlapping;
-finish every task; and stay within the 16-task limit. Extended launch times
-appear under `histogrammedExtendedLaunch` in `MXAppLaunchMetric`.
-
-## Xcode Organizer Integration
-
-Xcode Organizer shows aggregated MetricKit data across opted-in users. Use it for trend analysis alongside on-device collection routed to your own backend.
-
-See [references/metrickit-patterns.md](references/metrickit-patterns.md) for Organizer tab details.
-
-## Scope Boundaries
-
-Use this skill for production MetricKit ingestion, payload export, custom
-MetricKit signposts, and diagnostic upload/symbolication. Route SwiftUI runtime
-stutters, body-update cost, identity churn, and view invalidation fixes to
-`swiftui-performance`. Route local Instruments, LLDB, Memory Graph, and
-`xctrace` workflows to `debugging-instruments`. When explaining production
-telemetry, distinguish daily metric payloads from supported diagnostics that
-can arrive as soon as available.
-
-## Common Mistakes
-
-### DON'T: Subscribe to MXMetricManager too late
-
-Allocate `MXMetricManager.shared` and register the subscriber during app startup
-so the manager can accumulate reports and deliver any previously undelivered
-daily reports. Registering from a later view lifecycle hook is too easy to miss.
-
-```swift
-// WRONG  -  subscribing in a view controller
-override func viewDidLoad() {
-    super.viewDidLoad()
-    MXMetricManager.shared.add(self)
-}
-
-// CORRECT  -  subscribe in application(_:didFinishLaunchingWithOptions:)
-func application(
-    _ application: UIApplication,
-    didFinishLaunchingWithOptions opts: [UIApplication.LaunchOptionsKey: Any]?
-) -> Bool {
-    MXMetricManager.shared.add(metricsSubscriber)
-    return true
+@MainActor
+func prepareCatalog() async throws {
+    try MXMetricManager.extendLaunchMeasurement(forTaskID: warmCatalog)
+    defer { try? MXMetricManager.finishExtendedLaunchMeasurement(forTaskID: warmCatalog) }
+    try await catalog.openStore()
 }
 ```
 
-### DON'T: Ignore MXDiagnosticPayload
+Rules: make both calls on the main thread; begin the earliest task while no
+scene is active yet; tasks may overlap; finish every task you start; at most
+16 tasks. The result lands in `histogrammedExtendedLaunch` on
+`MXAppLaunchMetric`.
 
-Only handling `MXMetricPayload` means you miss crash, hang, and disk-write
-diagnostics  -  the most actionable data MetricKit provides.
+## Xcode Organizer
 
-```swift
-// WRONG  -  only implementing metric callback
-func didReceive(_ payloads: [MXMetricPayload]) { /* ... */ }
+Organizer shows MetricKit data aggregated across users who share analytics.
+Use it for trends and regressions, and your own collection for detail.
 
-// CORRECT  -  implement both callbacks
-func didReceive(_ payloads: [MXMetricPayload]) { /* ... */ }
-func didReceive(_ payloads: [MXDiagnosticPayload]) { /* ... */ }
-```
-
-### DON'T: Process payloads without persisting first
-
-Do not assume callback delivery will repeat if your own processing fails. Save
-the raw JSON before parsing, symbolication, or upload work.
-
-```swift
-// WRONG  -  process inline, crash loses data
-func didReceive(_ payloads: [MXDiagnosticPayload]) {
-    for p in payloads {
-        riskyProcessing(p)  // If this crashes, payload is gone
-    }
-}
-
-// CORRECT  -  persist raw JSON first, then process
-func didReceive(_ payloads: [MXDiagnosticPayload]) {
-    for p in payloads {
-        let json = p.jsonRepresentation()
-        try? json.write(to: localCacheURL())   // Safe on disk
-        Task.detached { self.processAsync(json) }
-    }
-}
-```
-
-### DON'T: Do heavy work synchronously in didReceive
+## Scope
 
-Apple documents that it is safe to process payloads on a separate thread. Keep
-the subscriber callback small: persist the JSON, then move expensive parsing
-or uploading out of the callback.
-
-```swift
-// WRONG  -  synchronous upload in callback
-func didReceive(_ payloads: [MXMetricPayload]) {
-    for p in payloads {
-        let data = p.jsonRepresentation()
-        URLSession.shared.uploadTask(with: request, from: data).resume()  // sync wait
-    }
-}
-
-// CORRECT  -  persist and dispatch async
-func didReceive(_ payloads: [MXMetricPayload]) {
-    for p in payloads {
-        let json = p.jsonRepresentation()
-        persistLocally(json)
-        Task.detached(priority: .utility) {
-            await self.uploadToBackend(json)
-        }
-    }
-}
-```
+In scope: ingesting production payloads, exporting them, custom signposts,
+uploading and symbolicating diagnostics. Out of scope:
 
-### DON'T: Expect immediate data in development
+- SwiftUI stutters, expensive `body` evaluation, identity or invalidation
+  fixes: `swiftui-performance`
+- Local Instruments sessions, LLDB, Memory Graph, `xctrace`: `debugging-instruments`
 
-MetricKit aggregates data over 24-hour windows. Payloads do not arrive
-immediately after instrumenting. Use Xcode Organizer or simulated payloads
-for faster iteration during development.
+Keep the delivery model straight: metric payloads are daily aggregates;
+diagnostics may arrive right away. MetricKit is a production signal, not an
+instant local debugging tool.
 
-### DON'T: Invent MetricKit signpost IDs
+## Common mistakes
 
-`MXSignpostIntervalData.makeSignpostID(log:)` is not documented MetricKit API.
-For basic MetricKit custom metrics, create an `MXMetricManager` log handle and
-call `mxSignpost(.begin/.end, log:name:)` without `OSSignpostID` allocation or
-custom `dso`, `signpostID`, or `format` arguments.
+- **Subscribing late**, for example in a view controller's `viewDidLoad`.
+  Subscribe at launch.
+- **Handling only metric payloads.** Crashes, hangs and disk-write
+  exceptions arrive through the diagnostic callback.
+- **Processing before saving.** If parsing crashes, the payload may never be
+  redelivered. Write the JSON to a local cache first.
+- **Heavy work in the callback.** Apple documents that processing on another
+  thread is safe; keep the callback short and move uploads to
+  `Task.detached(priority: .utility)`.
+- **Expecting payloads during development.** Metrics aggregate over 24 hours;
+  use Organizer, or Xcode's Debug > Simulate MetricKit Payloads.
+- **Calling `MXSignpostIntervalData.makeSignpostID(log:)`.** It is not a
+  documented MetricKit API.
 
-## Review Checklist
+## Review checklist
 
-- [ ] `MXMetricManager.shared.add(subscriber)` called in `application(_:didFinishLaunchingWithOptions:)` or `App.init`
-- [ ] Subscriber conforms to `MXMetricManagerSubscriber` and inherits `NSObject`
-- [ ] Both `didReceive(_: [MXMetricPayload])` and `didReceive(_: [MXDiagnosticPayload])` implemented
-- [ ] Raw `jsonRepresentation()` persisted to disk before processing
-- [ ] Heavy processing dispatched asynchronously after raw payload persistence
-- [ ] `MXCallStackTree` JSON uploaded with dSYMs for symbolication
-- [ ] Custom signpost metrics limited to critical code paths
-- [ ] `pastPayloads` and `pastDiagnosticPayloads` checked on launch for missed deliveries
-- [ ] Extended launch tasks call the throwing `MXMetricManager` type methods on the main thread and finish every started task
-- [ ] Analytics backend accepts and stores MetricKit JSON format
-- [ ] Xcode Organizer reviewed for regression trends alongside on-device data
+- [ ] `MXMetricManager.shared.add(_:)` runs at launch or in `App.init`
+- [ ] Subscriber is an `NSObject` conforming to `MXMetricManagerSubscriber`
+- [ ] Both `didReceive` callbacks implemented
+- [ ] Payload JSON persisted before processing
+- [ ] Heavy work happens asynchronously after persistence
+- [ ] Call-stack JSON uploaded along with dSYMs
+- [ ] Custom signposts limited to critical paths
+- [ ] Past payloads read at launch
+- [ ] Extended launch calls the static `try` methods from the main thread and ends each task it began
+- [ ] Backend stores the raw MetricKit JSON
+- [ ] Organizer checked for regressions
 
 ## References
 
-- Extended patterns: [references/metrickit-patterns.md](references/metrickit-patterns.md)
-- [MetricKit framework](https://sosumi.ai/documentation/metrickit)
-- [MXMetricManager](https://sosumi.ai/documentation/metrickit/mxmetricmanager)
-- [MXMetricManagerSubscriber](https://sosumi.ai/documentation/metrickit/mxmetricmanagersubscriber)
-- [MXMetricPayload](https://sosumi.ai/documentation/metrickit/mxmetricpayload)
-- [MXDiagnosticPayload](https://sosumi.ai/documentation/metrickit/mxdiagnosticpayload)
+- [MetricKit patterns](references/metrickit-patterns.md): crash and hang handlers, signposts end to end, export and upload, past payloads, extended launch rules, Organizer tabs, documentation links
+- https://developer.apple.com/documentation/metrickit
+- https://developer.apple.com/documentation/metrickit/mxmetricmanager
+- https://developer.apple.com/documentation/metrickit/mxmetricmanagersubscriber
+- https://developer.apple.com/documentation/metrickit/mxmetricpayload
+- https://developer.apple.com/documentation/metrickit/mxdiagnosticpayload