@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/speech-recognition/SKILL.md

@@ -1,16 +1,24 @@
 ---
 name: speech-recognition
-description: "Transcribe speech to text using the Speech framework. Use when implementing live microphone transcription with AVAudioEngine, recognizing pre-recorded audio files, configuring on-device vs server-based recognition, handling authorization flows, or adopting the new SpeechAnalyzer API (iOS 26+) for modern async/await speech-to-text."
+description: "Transcribe speech to text using Apple's Speech framework. Use when implementing live microphone transcription with AVAudioEngine, recognizing recorded audio files, handling speech and microphone authorization, choosing on-device vs server-backed SFSpeechRecognizer behavior, or adopting SpeechAnalyzer, SpeechTranscriber, DictationTranscriber, AssetInventory, and async result streams on iOS 26+."
 ---
 
 # Speech Recognition
 
 Transcribe live and pre-recorded audio to text using Apple's Speech framework.
-Covers `SFSpeechRecognizer` (iOS 10+) and the new `SpeechAnalyzer` API (iOS 26+).
+Covers `SpeechAnalyzer` / `SpeechTranscriber` (iOS 26+) and
+`SFSpeechRecognizer` (iOS 10+). Targets Swift 6.3 / iOS 26+ while preserving
+fallback guidance for apps that support older OS versions.
+
+**Scope boundary:** Use this skill for speech-to-text recognition, speech
+authorization, microphone capture plumbing, and result handling. Hand off text
+analysis, language identification after transcription, sentiment, embeddings,
+and translation to `natural-language`; hand off audio playback UI to `avkit`;
+hand off summarization or generation over transcripts to `apple-on-device-ai`.
 
 ## Contents
 
-- [SpeechAnalyzer (iOS 26+)](#speechanalyzer-ios-26)
+- [SpeechAnalyzer Strategy (iOS 26+)](#speechanalyzer-strategy-ios-26)
 - [SFSpeechRecognizer Setup](#sfspeechrecognizer-setup)
 - [Authorization](#authorization)
 - [Live Microphone Transcription](#live-microphone-transcription)
@@ -21,87 +29,45 @@ Covers `SFSpeechRecognizer` (iOS 10+) and the new `SpeechAnalyzer` API (iOS 26+)
 - [Review Checklist](#review-checklist)
 - [References](#references)
 
-## SpeechAnalyzer (iOS 26+)
-
-`SpeechAnalyzer` is an actor-based API introduced in iOS 26 that replaces
-`SFSpeechRecognizer` for new projects. It uses Swift concurrency, `AsyncSequence`
-for results, and supports modular analysis via `SpeechTranscriber`.
-
-### Basic transcription with SpeechAnalyzer
-
-```swift
-import Speech
-
-// 1. Create a transcriber module
-guard let locale = SpeechTranscriber.supportedLocale(
-    equivalentTo: Locale.current
-) else { return }
-let transcriber = SpeechTranscriber(locale: locale, preset: .offlineTranscription)
-
-// 2. Ensure assets are installed
-if let request = try await AssetInventory.assetInstallationRequest(
-    supporting: [transcriber]
-) {
-    try await request.downloadAndInstall()
-}
-
-// 3. Create input stream and analyzer
-let (inputSequence, inputBuilder) = AsyncStream.makeStream(of: AnalyzerInput.self)
-let audioFormat = await SpeechAnalyzer.bestAvailableAudioFormat(
-    compatibleWith: [transcriber]
-)
-let analyzer = SpeechAnalyzer(modules: [transcriber])
-
-// 4. Feed audio buffers (from AVAudioEngine or file)
-Task {
-    // Append PCM buffers converted to audioFormat
-    let pcmBuffer: AVAudioPCMBuffer = // ... your audio buffer
-    inputBuilder.yield(AnalyzerInput(buffer: pcmBuffer))
-    inputBuilder.finish()
-}
-
-// 5. Consume results
-Task {
-    for try await result in transcriber.results {
-        let text = String(result.text.characters)
-        print(text)
-    }
-}
-
-// 6. Run analysis
-let lastSampleTime = try await analyzer.analyzeSequence(inputSequence)
-
-// 7. Finalize
-if let lastSampleTime {
-    try await analyzer.finalizeAndFinish(through: lastSampleTime)
-} else {
-    try analyzer.cancelAndFinishNow()
-}
-```
-
-### Transcribing an audio file with SpeechAnalyzer
-
-```swift
-let transcriber = SpeechTranscriber(locale: locale, preset: .offlineTranscription)
-let audioFile = try AVAudioFile(forReading: fileURL)
-let analyzer = SpeechAnalyzer(
-    inputAudioFile: audioFile, modules: [transcriber], finishAfterFile: true
-)
-for try await result in transcriber.results {
-    print(String(result.text.characters))
-}
-```
-
-### Key differences from SFSpeechRecognizer
-
-| Feature | SFSpeechRecognizer | SpeechAnalyzer |
-|---|---|---|
-| Concurrency | Callbacks/delegates | async/await + AsyncSequence |
-| Type | `class` | `actor` |
-| Modules | Monolithic | Composable (`SpeechTranscriber`, `SpeechDetector`) |
-| Audio input | `append(_:)` on request | `AsyncStream<AnalyzerInput>` |
-| Availability | iOS 10+ | iOS 26+ |
-| On-device | `requiresOnDeviceRecognition` | Asset-based via `AssetInventory` |
+## SpeechAnalyzer Strategy (iOS 26+)
+
+Use `SpeechAnalyzer` for modern iOS 26+ speech analysis, especially long-form
+recordings, live transcription, time-indexed transcripts, and fully on-device
+flows. Keep `SFSpeechRecognizer` for iOS 10+ deployment targets, server-backed
+locale coverage, or existing callback/delegate implementations.
+
+Read [SpeechAnalyzer patterns](references/speechanalyzer-patterns.md) when
+implementing an iOS 26+ transcription pipeline, model asset handling, volatile
+results, or file/buffer examples.
+
+### SpeechAnalyzer setup checklist
+
+1. Choose the module:
+   - `SpeechTranscriber` for the newer general-purpose on-device model.
+   - `DictationTranscriber` when `SpeechTranscriber` is unavailable for the
+     current device or locale and dictation-compatible support is acceptable.
+   - `SpeechDetector` only in conjunction with a transcriber when voice
+     activity detection is worth the accuracy/power tradeoff.
+2. Check support before creating the session:
+   - `SpeechTranscriber.isAvailable`
+   - `SpeechTranscriber.supportedLocale(equivalentTo:)`
+   - `SpeechTranscriber.installedLocales` / `supportedLocales` when showing
+     language choices.
+3. Pick a documented preset:
+   - `.transcription` for basic accurate transcription.
+   - `.progressiveTranscription` for live UI updates.
+   - `.timeIndexedProgressiveTranscription` when playback highlighting needs
+     `audioTimeRange`.
+4. Install required assets with `AssetInventory.assetInstallationRequest`.
+5. Convert live audio buffers to
+   `SpeechAnalyzer.bestAvailableAudioFormat(compatibleWith:)` before yielding
+   `AnalyzerInput`.
+6. Consume module results from their `AsyncSequence` in a separate task.
+7. Finish explicitly with `finalizeAndFinish(through:)`,
+   `finalizeAndFinishThroughEndOfInput()`, or `cancelAndFinishNow()`.
+
+Do not use an `offlineTranscription` preset; Apple does not document one.
+Finishing an `AsyncStream` input sequence does not finish the analyzer session.
 
 ## SFSpeechRecognizer Setup
 
@@ -138,7 +104,7 @@ final class SpeechManager: NSObject, SFSpeechRecognizerDelegate {
         _ speechRecognizer: SFSpeechRecognizer,
         availabilityDidChange available: Bool
     ) {
-        // Update UI — disable record button when unavailable
+        // Update UI  -  disable record button when unavailable
     }
 }
 ```
@@ -259,10 +225,14 @@ func transcribeFile(at url: URL) async throws -> String {
     request.shouldReportPartialResults = false
 
     return try await withCheckedThrowingContinuation { continuation in
+        var didResume = false
         recognizer.recognitionTask(with: request) { result, error in
+            guard !didResume else { return }
             if let error {
+                didResume = true
                 continuation.resume(throwing: error)
             } else if let result, result.isFinal {
+                didResume = true
                 continuation.resume(
                     returning: result.bestTranscription.formattedString
                 )
@@ -274,7 +244,10 @@ func transcribeFile(at url: URL) async throws -> String {
 
 ## On-Device vs Server Recognition
 
-On-device recognition (iOS 13+) works offline but supports fewer locales:
+`SFSpeechRecognizer` can use on-device recognition for supported locales on
+iOS 13+. If `supportsOnDeviceRecognition` is false, the recognizer requires a
+network connection. `requiresOnDeviceRecognition` only has effect when the
+recognizer supports it.
 
 ```swift
 let recognizer = SFSpeechRecognizer(locale: Locale(identifier: "en-US"))!
@@ -286,10 +259,11 @@ if recognizer.supportsOnDeviceRecognition {
 }
 ```
 
-> **Tip:** On-device recognition avoids network latency and the one-minute
-> audio limit imposed by server-based recognition. However, accuracy may be
-> lower and not all locales are supported. Check `supportsOnDeviceRecognition`
-> before forcing on-device mode.
+`SFSpeechRecognizer` requests may still be a poor fit for long-form capture.
+Apple documents a roughly one-minute task limit for speech recognition and
+other service limits. For long recordings on iOS 26+, prefer `SpeechAnalyzer`;
+otherwise chunk or restart recognition before the limit and preserve transcript
+state across tasks.
 
 ## Handling Results
 
@@ -303,10 +277,10 @@ recognizer.recognitionTask(with: request) { result, error in
     guard let result else { return }
 
     if result.isFinal {
-        // Final transcription — recognition is complete
+        // Final transcription  -  recognition is complete
         let final = result.bestTranscription.formattedString
     } else {
-        // Partial result — may change as more audio is processed
+        // Partial result  -  may change as more audio is processed
         let partial = result.bestTranscription.formattedString
     }
 }
@@ -353,7 +327,7 @@ request.contextualStrings = ["SwiftUI", "Xcode", "CloudKit"]
 ```swift
 // ❌ DON'T: Only request speech authorization for live audio
 SFSpeechRecognizer.requestAuthorization { status in
-    // Missing microphone permission — audio engine will fail
+    // Missing microphone permission  -  audio engine will fail
     self.startRecording()
 }
 
@@ -410,7 +384,7 @@ recognizer.recognitionTask(with: request) { result, error in
 ```swift
 // ❌ DON'T: Force on-device without checking support
 let request = SFSpeechAudioBufferRecognitionRequest()
-request.requiresOnDeviceRecognition = true // May silently fail
+request.requiresOnDeviceRecognition = true // Ignored unless the recognizer supports it
 
 // ✅ DO: Check support before requiring on-device
 if recognizer.supportsOnDeviceRecognition {
@@ -425,15 +399,48 @@ if recognizer.supportsOnDeviceRecognition {
 ```swift
 // ❌ DON'T: Start one long continuous recognition session
 func startRecording() {
-    // This will be cut off after ~60 seconds (server-based)
+    // SFSpeechRecognizer tasks can be cut off after about 60 seconds
 }
 
-// ✅ DO: Restart recognition when approaching the limit
-func startRecording() {
-    // Use a timer to restart before the limit
-    recognitionTimer = Timer.scheduledTimer(withTimeInterval: 55, repeats: false) {
-        [weak self] _ in
-        self?.restartRecognition()
+// ✅ DO: roll the segment before the limit and let cleanup end audio once
+func scheduleRecognitionRollover() {
+    recognitionTimer = Timer.scheduledTimer(withTimeInterval: 55, repeats: false) { [weak self] _ in
+        self?.commitLatestPartialText()
+        self?.stopTranscribing()     // owns endAudio(), tap removal, and task cancellation
+        try? self?.startTranscribing()
+    }
+}
+```
+`SFSpeechRecognitionTask` exposes `finish()`, `cancel()`, `state`, and `error`;
+do not invent task properties such as `recognitionTask` to restart work. Keep
+the active `SFSpeechAudioBufferRecognitionRequest` in your manager and call
+`endAudio()` from one cleanup path only.
+
+### Treating SpeechAnalyzer input completion as session completion
+
+```swift
+// ❌ DON'T: Only finish the AsyncStream and expect result streams to close
+inputBuilder.finish()
+
+// ✅ DO: explicitly finish or cancel the analyzer session
+let lastSampleTime = try await analyzer.analyzeSequence(inputSequence)
+if let lastSampleTime {
+    try await analyzer.finalizeAndFinish(through: lastSampleTime)
+} else {
+    try analyzer.cancelAndFinishNow()
+}
+```
+
+### Duplicating volatile SpeechAnalyzer results
+
+```swift
+// ✅ Replace volatile text with the finalized result for the same audio range
+for try await result in transcriber.results {
+    if result.isFinal {
+        volatileTranscript = AttributedString()
+        finalizedTranscript.append(result.text)
+    } else {
+        volatileTranscript = result.text
     }
 }
 ```
@@ -444,7 +451,7 @@ func startRecording() {
 // ❌ DON'T: Start a new task without canceling the previous one
 func startRecording() {
     recognitionTask = recognizer.recognitionTask(with: request) { ... }
-    // Previous task is still running — undefined behavior
+    // Previous task is still running  -  undefined behavior
 }
 
 // ✅ DO: Cancel existing task before creating a new one
@@ -466,15 +473,21 @@ func startRecording() {
 - [ ] Previous `recognitionTask` is canceled before starting a new one
 - [ ] `supportsOnDeviceRecognition` is checked before requiring on-device mode
 - [ ] Partial results are handled separately from final (`isFinal`) results
-- [ ] One-minute limit is accounted for in server-based recognition
+- [ ] `SFSpeechRecognizer` one-minute/service limits are accounted for
 - [ ] For iOS 26+: `AssetInventory` assets are installed before using `SpeechAnalyzer`
-- [ ] For iOS 26+: `SpeechTranscriber.supportedLocale(equivalentTo:)` is checked
+- [ ] For iOS 26+: `SpeechTranscriber.isAvailable` and locale support are checked
+- [ ] For iOS 26+: live buffers are converted to the analyzer-compatible format
+- [ ] For iOS 26+: analyzer sessions are explicitly finalized or canceled
+- [ ] For iOS 26+: volatile results are replaced by finalized results, not duplicated
 
 ## References
 
 - [Speech framework](https://sosumi.ai/documentation/speech)
 - [SpeechAnalyzer](https://sosumi.ai/documentation/speech/speechanalyzer)
 - [SpeechTranscriber](https://sosumi.ai/documentation/speech/speechtranscriber)
+- [SpeechTranscriber.Preset](https://sosumi.ai/documentation/speech/speechtranscriber/preset)
+- [DictationTranscriber](https://sosumi.ai/documentation/speech/dictationtranscriber)
+- [SpeechDetector](https://sosumi.ai/documentation/speech/speechdetector)
 - [SFSpeechRecognizer](https://sosumi.ai/documentation/speech/sfspeechrecognizer)
 - [SFSpeechAudioBufferRecognitionRequest](https://sosumi.ai/documentation/speech/sfspeechaudiobufferrecognitionrequest)
 - [SFSpeechURLRecognitionRequest](https://sosumi.ai/documentation/speech/sfspeechurlrecognitionrequest)
@@ -483,3 +496,4 @@ func startRecording() {
 - [AssetInventory](https://sosumi.ai/documentation/speech/assetinventory)
 - [Asking Permission to Use Speech Recognition](https://sosumi.ai/documentation/speech/asking-permission-to-use-speech-recognition)
 - [Recognizing Speech in Live Audio](https://sosumi.ai/documentation/speech/recognizing-speech-in-live-audio)
+- [Bring advanced speech-to-text to your app with SpeechAnalyzer](https://sosumi.ai/videos/play/wwdc2025/277)

package/pipeline/skills/shared/external/speech-recognition/evals/evals.json

@@ -0,0 +1,49 @@
+{
+  "skill_name": "speech-recognition",
+  "evals": [
+    {
+      "id": 0,
+      "name": "speechanalyzer-live-transcription",
+      "prompt": "I'm building an iOS 26 meeting recorder with live transcript text and word highlighting during playback. Sketch the SpeechAnalyzer implementation shape, including model setup, audio input, result handling, and cleanup.",
+      "expected_output": "An iOS 26 SpeechAnalyzer plan that uses current SpeechTranscriber APIs, installs assets, converts live audio buffers, handles volatile/final results, and explicitly finishes the analyzer session.",
+      "files": [],
+      "assertions": [
+        "Uses SpeechAnalyzer with SpeechTranscriber and a documented preset such as .timeIndexedProgressiveTranscription, not .offlineTranscription.",
+        "Checks SpeechTranscriber.isAvailable and supportedLocale(equivalentTo:) before starting transcription.",
+        "Installs or verifies model assets with AssetInventory.assetInstallationRequest(supporting:) before analysis.",
+        "Converts AVAudioEngine microphone buffers to SpeechAnalyzer.bestAvailableAudioFormat(compatibleWith:) before yielding AnalyzerInput.",
+        "Handles volatile results separately from finalized results so live text is replaced rather than duplicated.",
+        "Explicitly finalizes or cancels the analyzer session after input ends."
+      ]
+    },
+    {
+      "id": 1,
+      "name": "sfspeechrecognizer-live-review",
+      "prompt": "Review this iOS live dictation plan: request only NSSpeechRecognitionUsageDescription, start AVAudioEngine immediately, use SFSpeechRecognizer forever in one recognition task, force requiresOnDeviceRecognition for every locale, and ignore availability changes. Give corrected guidance and focused Swift snippets.",
+      "expected_output": "A correction-focused SFSpeechRecognizer review that covers speech and microphone authorization, live audio setup, availability changes, on-device checks, task cleanup, and recognition duration limits.",
+      "files": [],
+      "assertions": [
+        "Requires both NSSpeechRecognitionUsageDescription and NSMicrophoneUsageDescription for live microphone transcription.",
+        "Requests speech recognition authorization and microphone record permission before activating the audio session or starting AVAudioEngine.",
+        "Uses SFSpeechRecognizerDelegate or availability handling for recognition service changes.",
+        "Checks supportsOnDeviceRecognition before setting requiresOnDeviceRecognition and gives a fallback when unsupported.",
+        "Accounts for SFSpeechRecognizer recognition duration/service limits instead of running one unbounded task.",
+        "Stops AVAudioEngine, removes the input tap, ends audio, and cancels or clears the recognition task during cleanup."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "speech-boundary-routing",
+      "prompt": "A notes feature records a spoken note, transcribes it, detects the text language and sentiment, translates a summary to Spanish, plays back the recording with captions, and optionally uses Apple Intelligence to summarize it. Which parts belong in the speech-recognition skill and which should be handed to sibling skills?",
+      "expected_output": "A boundary-aware routing answer that keeps speech-to-text and microphone capture in Speech, and routes text analysis, translation, playback UI, and generative summarization to the correct sibling skills.",
+      "files": [],
+      "assertions": [
+        "Keeps microphone capture, speech authorization, SpeechAnalyzer or SFSpeechRecognizer transcription, and transcript result handling in the speech-recognition scope.",
+        "Routes language detection, sentiment, text embeddings, and translation to the natural-language skill after transcription exists.",
+        "Routes playback UI, captions during media playback, or AVPlayer/AVKit concerns to the avkit skill.",
+        "Routes Apple Intelligence or Foundation Models summarization to the apple-on-device-ai skill.",
+        "Does not present NaturalLanguage as a speech-to-text framework or Speech as a general text-analysis framework."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/speech-recognition/references/speechanalyzer-patterns.md

@@ -0,0 +1,171 @@
+# SpeechAnalyzer Patterns
+
+Use this reference when implementing iOS 26+ speech-to-text with
+`SpeechAnalyzer`, `SpeechTranscriber`, `DictationTranscriber`, `SpeechDetector`,
+or `AssetInventory`.
+
+## Contents
+
+- [Choosing Modules](#choosing-modules)
+- [Preparing Assets](#preparing-assets)
+- [Transcribing Files](#transcribing-files)
+- [Live Audio](#live-audio)
+- [Handling Results](#handling-results)
+- [Finishing Sessions](#finishing-sessions)
+- [References](#references)
+
+## Choosing Modules
+
+Prefer `SpeechTranscriber` for the newer general-purpose on-device model.
+Before building UI around it, check both device and locale support:
+
+```swift
+guard SpeechTranscriber.isAvailable,
+      let locale = SpeechTranscriber.supportedLocale(equivalentTo: Locale.current)
+else {
+    // Disable the feature or try DictationTranscriber for compatible devices/locales.
+    return
+}
+```
+
+Use documented presets only:
+
+- `.transcription` for basic accurate transcription.
+- `.transcriptionWithAlternatives` for editing suggestions.
+- `.timeIndexedTranscriptionWithAlternatives` for audio-time metadata plus alternatives.
+- `.progressiveTranscription` for low-latency live UI updates.
+- `.timeIndexedProgressiveTranscription` for live UI updates with time ranges.
+
+Use `DictationTranscriber` when `SpeechTranscriber` is unavailable and the app
+can accept dictation-model behavior. Add `SpeechDetector` only with a
+transcriber module, and only when voice activity detection is worth the risk of
+dropping speech-like audio.
+
+## Preparing Assets
+
+`SpeechAnalyzer` modules require model assets. The system installs and shares
+them outside the app bundle, but the app must request installation for the
+module configuration it plans to use.
+
+```swift
+let transcriber = SpeechTranscriber(locale: locale, preset: .transcription)
+
+if let request = try await AssetInventory.assetInstallationRequest(
+    supporting: [transcriber]
+) {
+    try await request.downloadAndInstall()
+}
+```
+
+For language pickers, use `installedLocales`, `supportedLocales`, and
+`AssetInventory.status(forModules:)` to distinguish installed, downloadable,
+and unsupported choices. The app has a limited number of locale reservations;
+release unused reservations with `AssetInventory.release(reservedLocale:)`.
+
+## Transcribing Files
+
+For files, let the analyzer convert the file to a compatible format and finish
+the session after the file is consumed.
+
+```swift
+func transcribeFile(at url: URL, locale: Locale) async throws -> AttributedString {
+    guard let supportedLocale = SpeechTranscriber.supportedLocale(equivalentTo: locale) else {
+        throw SpeechError.unsupportedLocale
+    }
+
+    let transcriber = SpeechTranscriber(
+        locale: supportedLocale,
+        preset: .transcription
+    )
+
+    if let request = try await AssetInventory.assetInstallationRequest(
+        supporting: [transcriber]
+    ) {
+        try await request.downloadAndInstall()
+    }
+
+    let analyzer = SpeechAnalyzer(modules: [transcriber])
+    async let transcript = transcriber.results.reduce(into: AttributedString()) {
+        text, result in
+        text.append(result.text)
+    }
+
+    let file = try AVAudioFile(forReading: url)
+    let lastSampleTime = try await analyzer.analyzeSequence(from: file)
+    if let lastSampleTime {
+        try await analyzer.finalizeAndFinish(through: lastSampleTime)
+    } else {
+        try analyzer.cancelAndFinishNow()
+    }
+
+    return try await transcript
+}
+```
+
+## Live Audio
+
+For live audio, create an `AsyncStream<AnalyzerInput>`, convert microphone
+buffers to the analyzer-compatible format, yield them, and consume results in a
+separate task.
+
+```swift
+let transcriber = SpeechTranscriber(
+    locale: locale,
+    preset: .timeIndexedProgressiveTranscription
+)
+let analyzer = SpeechAnalyzer(modules: [transcriber])
+let audioFormat = await SpeechAnalyzer.bestAvailableAudioFormat(
+    compatibleWith: [transcriber]
+)
+let (inputSequence, inputBuilder) = AsyncStream.makeStream(of: AnalyzerInput.self)
+
+// In the audio-engine tap, convert each AVAudioPCMBuffer to audioFormat first.
+inputBuilder.yield(AnalyzerInput(buffer: convertedBuffer))
+```
+
+Use `AVAudioConverter` or an existing project audio pipeline for the conversion.
+Do not feed arbitrary input-node formats directly unless they already match a
+compatible analyzer format.
+
+## Handling Results
+
+`SpeechTranscriber.Result.text` is an `AttributedString`. Time-indexed presets
+include audio time range attributes that can drive playback highlighting.
+
+When using progressive presets, volatile results may be replaced by later final
+results. Keep volatile display state separate so the UI does not duplicate text.
+
+```swift
+for try await result in transcriber.results {
+    if result.isFinal {
+        volatileTranscript = AttributedString()
+        finalizedTranscript.append(result.text)
+    } else {
+        volatileTranscript = result.text
+    }
+}
+```
+
+## Finishing Sessions
+
+The analyzer can only analyze one input sequence at a time. Ending your stream
+does not finish the analyzer session; call a finish or cancel method.
+
+Use:
+
+- `finalizeAndFinish(through:)` after `analyzeSequence(_:)` returns a final sample time.
+- `finalizeAndFinishThroughEndOfInput()` after autonomous `start(inputSequence:)`.
+- `cancelAndFinishNow()` for immediate cancellation.
+
+After the session finishes, result streams terminate and most analyzer methods
+no longer accept new work. Create a new analyzer for a new finished session.
+
+## References
+
+- [SpeechAnalyzer](https://sosumi.ai/documentation/speech/speechanalyzer)
+- [SpeechTranscriber](https://sosumi.ai/documentation/speech/speechtranscriber)
+- [SpeechTranscriber.Preset](https://sosumi.ai/documentation/speech/speechtranscriber/preset)
+- [DictationTranscriber](https://sosumi.ai/documentation/speech/dictationtranscriber)
+- [SpeechDetector](https://sosumi.ai/documentation/speech/speechdetector)
+- [AssetInventory](https://sosumi.ai/documentation/speech/assetinventory)
+- [WWDC25: Bring advanced speech-to-text to your app with SpeechAnalyzer](https://sosumi.ai/videos/play/wwdc2025/277)

package/pipeline/skills/shared/external/spm-build-analysis/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: spm-build-analysis
+description: Analyze Swift Package Manager dependencies, package plugins, module variants, and CI-oriented build overhead that slow Xcode builds. Use when a developer suspects packages, plugins, or dependency graph shape are hurting clean or incremental build performance, mentions SPM slowness, package resolution time, build plugin overhead, duplicate module builds from configuration drift, circular dependencies between modules, oversized modules needing splitting, or modularization best practices.
+user-invocable: false
+---
+
+# SPM Build Analysis
+
+Use this skill when package structure, plugins, or dependency configuration are likely contributing to slow Xcode builds.
+
+## Core Rules
+
+- Treat package analysis as evidence gathering first, not a mandate to replace dependencies.
+- Separate package-graph issues from project-setting issues.
+- Do not rewrite package manifests or dependency sources without explicit approval.
+
+## What To Inspect
+
+- `Package.swift` and `Package.resolved`
+- local packages vs remote packages
+- package plugin and build-tool usage
+- binary target footprint
+- dependency layering, repeated imports, and potential cycles
+- build logs or timing summaries that show package-related work
+
+## Verification Before Recommending
+
+Before including any local package in a recommendation, verify that it is actually part of the project's dependency graph. A `Vendor/` directory may contain packages that are not linked to any target.
+
+- Check `project.pbxproj` for `XCLocalSwiftPackageReference` entries that reference the package path.
+- Check `XCSwiftPackageProductDependency` entries to confirm the package's product is linked to at least one target.
+- If a local package exists on disk but is not referenced in the project, do not include it in build-time recommendations.
+
+When recommending version pins for branch-tracked dependencies:
+
+- Use the helper script to scan all branch-pinned dependencies at once:
+  ```bash
+  python3 scripts/check_spm_pins.py --project App.xcodeproj
+  ```
+  This checks `git ls-remote --tags` for each branch-pinned package and reports which have tags available for pinning.
+- If no tags exist, recommend pinning to a specific commit revision hash for determinism instead.
+- Note which packages are branch-pinned because the upstream simply has no tags, versus packages that have tags but are intentionally tracking a branch.
+
+## Focus Areas
+
+- package graph shape and how much work changes trigger downstream
+- plugin overhead during local development and CI
+- checkout or fetch cost signals that show up in clean environments
+- configuration drift that forces duplicate module builds
+- risks from package targets that use different macros or options while sharing dependencies
+- dependency direction violations (features depending on each other instead of shared lower layers)
+- circular dependencies between modules (extract shared contracts into a protocol module)
+- oversized modules (200+ files) that widen incremental rebuild scope
+- umbrella modules using `@_exported import` that create hidden dependency chains
+- missing interface/implementation separation that blocks build parallelism
+- test targets depending on the app target instead of the module under test
+- Swift macro rebuild cascading: heavy use of Swift macros (e.g., TCA, swift-syntax-based libraries) can cause a trivial source change to cascade into near-full rebuilds because macro expansion invalidates downstream modules
+- `swift-syntax` building universally (all architectures) when no prebuilt binary is available, adding significant clean-build overhead
+- multi-platform build multiplication: adding a secondary platform target (e.g., watchOS) can cause shared SPM packages to build multiple times (e.g., iOS arm64, iOS x86_64, watchOS arm64), multiplying `SwiftCompile`, `SwiftEmitModule`, and `ScanDependencies` tasks
+
+## Modular SDK Migration Caveat
+
+Migrating a dependency from a monolithic target to a modular multi-target SDK (e.g., replacing one umbrella library with separate Core, RUM, Logs, Trace modules) does not automatically reduce build time. Modular targets increase the number of `SwiftCompile`, `SwiftEmitModule`, and `ScanDependencies` tasks because each target must be compiled, scanned, and emit its module independently. The build-time trade-off depends on the project's parallelism headroom and how many of the modular targets are actually needed.
+
+When considering a modular SDK migration:
+
+- Compare the total `SwiftCompile` task count before and after.
+- Benchmark both configurations before recommending the migration for build speed.
+- If the motivation is API surface reduction (importing only what you use), note that build time may stay flat or increase while import hygiene improves.
+- Only recommend modular SDK migration for build speed when the project currently compiles large portions of the monolithic SDK that it does not use, and the modular alternative lets it skip those unused portions entirely.
+
+## Explicit Module Dependency Angle
+
+When the same module appears multiple times in timing output, investigate whether different package or target options are forcing extra module variants. Uniform options often matter more than shaving a small amount of source code.
+
+## Reporting Format
+
+For each finding, include:
+
+- evidence
+- affected package or plugin
+- likely clean-build vs incremental-build impact
+- CI impact if relevant
+- estimated impact
+- approval requirement
+
+If the main problem is not package-related, hand off to [`xcode-project-analyzer`](../xcode-project-analyzer/SKILL.md) or [`xcode-compilation-analyzer`](../xcode-compilation-analyzer/SKILL.md) by reading the target skill's SKILL.md and applying its workflow to the same project context.
+
+## Additional Resources
+
+- For the detailed audit checklist, see [references/spm-analysis-checks.md](references/spm-analysis-checks.md)
+- For the shared recommendation structure, see [references/recommendation-format.md](references/recommendation-format.md)
+- For source citations, see [references/build-optimization-sources.md](references/build-optimization-sources.md)