@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/swiftui-performance/references/understanding-hangs-in-your-app.md

@@ -1,233 +1,146 @@
-# Understanding Hangs in Your App (Summary)
+# Hangs and the Main Run Loop
 
-Context: Apple guidance on identifying hangs caused by long-running main-thread
-work and understanding the main run loop.
+Based on Apple's article "Understanding hangs in your app" and the WWDC23
+session "Analyze hangs with Instruments".
 
-## Contents
-- What a hang is
-- Main-thread work stages
-- Triage workflow
-- Common root causes
-- Fix patterns
-- Verification checklist
-- Related SwiftUI implications
+## What Counts as a Hang
 
-## What a hang is
+A hang is a delay the user notices in a discrete interaction, such as a tap
+that does not respond. Almost always the main thread is busy for long enough
+to be felt.
 
-A hang is a noticeable delay in a discrete interaction. Apple commonly frames
-this as main-thread busy time long enough for the user to feel the UI stop
-responding.
+| Main thread busy for | Feels |
+|----------------------|-------|
+| Under about 100 ms | Immediate |
+| About 100 to 250 ms | Sticky |
+| Over about 250 ms | Probably a hang |
+| Several seconds | An obvious bug |
 
-Practical thresholds:
+The exact number matters less than whether the user felt the interaction was
+blocked. Suspect the main thread first.
 
-- Under ~100 ms usually feels immediate.
-- Around 100-250 ms starts to feel sticky.
-- Above ~250 ms is a likely hang candidate.
-- Multi-second stalls are usually obvious product bugs, not subtle perf issues.
+## How the Main Thread Spends a Frame
 
-The important point is not the exact number. A hang is user-perceived blocked
-interaction, and the main thread is usually where the problem lives.
+Three stages happen on the main thread:
 
-## Main-thread work stages
+1. The event is delivered to the view or responder that handles it.
+2. App code runs, changes state and schedules UI work.
+3. Core Animation commits the layer tree to the render server.
 
-A typical interaction flows through three stages on the main thread:
+If any stage runs long, the run loop cannot go back to sleep and pick up the
+next event. A healthy app is idle most of the time; a busy one lets taps,
+gestures, timers and redraws pile up.
 
-1. Event delivery to the target view or responder
-2. Your code mutating state, computing values, and scheduling UI changes
-3. Core Animation committing the frame tree to the render server
+Work isolated to the main actor still runs on the main thread. `@MainActor`
+makes code correct; it does not make it faster. Assume the main thread is
+overloaded until a profile shows otherwise.
 
-If any one of those stages runs too long, the main run loop cannot get back to
-sleep and cannot service the next event in time.
+## Triage
 
-## Main run loop model
+1. **Pick one concrete interaction.** "The Save button ignores taps for half a
+   second", "the push animation pauses before starting", "dismissing the sheet
+   freezes scrolling". Not "the app feels slow".
+2. **Record it** with the Hangs instrument, adding Time Profiler when needed.
+   Release build, real device, a path you can repeat, several repetitions.
+3. **Read the busy windows on the main thread** before looking at total CPU.
+   Is the time spent in app code, in synchronous I/O, in recomputing layout or
+   state, or waiting on a lock or an actor hop?
+4. **Remove or relocate the work.** Hiding it behind a spinner is a weak fix.
 
-The main run loop is a good mental model for hangs:
+## Common Causes
 
-- Healthy apps spend most of their time idle, waiting for work.
-- A busy run loop means new taps, gestures, timers, and redraw work queue up.
-- Main-actor tasks still execute on the main thread. Moving code to `@MainActor`
-  is a correctness tool, not a performance optimization.
+### Synchronous I/O
 
-If the UI is stalled, assume the main thread is overloaded until profiling
-proves otherwise.
-
-## Triage workflow
-
-### 1. Reproduce a single concrete interaction
-
-Start with one specific symptom:
-
-- tapping a button does nothing for half a second
-- pushing a detail screen pauses before animating
-- dismissing a sheet freezes scrolling underneath
-
-Avoid broad goals like "the app feels slow" until you isolate a single path.
-
-### 2. Record with Instruments
-
-Use the Hangs instrument, and pair it with Time Profiler when needed.
-
-Good capture setup:
-
-- Release build
-- real device
-- repeatable interaction path
-- enough repetitions to confirm the same stall pattern
-
-### 3. Inspect busy windows on the main thread
-
-Look for long busy periods instead of staring at total CPU first.
-
-Questions to answer:
-
-- Is the main thread blocked in app code?
-- Is it blocked in synchronous I/O?
-- Is it repeatedly recalculating layout or view state?
-- Is there a lock or actor hop forcing serialization?
-
-### 4. Reduce the work, not just the symptom
-
-A useful fix removes or re-locates expensive work. A weak fix only hides the
-stall behind a spinner while the main thread still does too much.
-
-## Common root causes
-
-### Synchronous I/O on the main thread
-
-Typical offenders:
-
-- file reads
-- JSON decoding for large payloads
-- image decoding
-- database fetches
-- Keychain work done inline with UI gestures
+Reading files, decoding large JSON, decoding images, database fetches and
+Keychain calls made inline in a gesture handler.
 
 ```swift
-// DON'T
-Button("Open") {
-    let data = try? Data(contentsOf: fileURL)
-    model = parse(data)
+// Blocks the main thread while the file is read and parsed.
+Button("Import") {
+    let data = try? Data(contentsOf: archiveURL)
+    entries = parseArchive(data)
 }
 
-// DO
-Button("Open") {
+// Starts the work, lets it run elsewhere, then publishes the result.
+Button("Import") {
     Task {
-        let data = try await loadFileData()
-        let parsed = try await parseModel(from: data)
-        await MainActor.run { model = parsed }
+        let parsed = await ArchiveReader.load(from: archiveURL)
+        await MainActor.run { entries = parsed }
     }
 }
 ```
 
-### Heavy work in event handlers
-
-A tap handler should kick off work, not do all the work inline.
+Event handlers should kick work off, not perform it:
 
 ```swift
-// DON'T
-func didTapRefresh() {
-    items = expensiveRebuildOfEntireList()
-}
-
-// DO
-func didTapRefresh() {
+func reloadTapped() {
     Task {
-        let rebuilt = await rebuildList()
-        await MainActor.run { items = rebuilt }
+        let rebuilt = await index.rebuild()
+        await MainActor.run { results = rebuilt }
     }
 }
 ```
 
-### Main-thread contention from layout or rendering
-
-SwiftUI and UIKit/AppKit can both stall if the view tree triggers too much work
-per interaction.
+When the caller is already on the main actor, a plain assignment after the
+`await` does the same as `MainActor.run`.
 
-Watch for:
+### Layout and rendering pressure
 
-- repeated formatter creation
-- image resizing in `body`
-- expensive attributed string generation during scroll
-- layout invalidations triggered by frequent geometry changes
+Signs: formatters created again and again, images resized in `body`, attributed
+strings built while scrolling, and invalidations driven by frequent geometry
+changes.
 
-### Locking and serialization
+### Waiting instead of working
 
-A hang may show up as main-thread waiting, not main-thread computing.
+A hang does not have to be computation:
 
-Examples:
-
-- a lock held by background work
-- synchronous dispatch back to main
-- a main-actor method waiting on another main-actor path
+- the main thread waits for a lock a background job holds,
+- code dispatches synchronously to the main queue,
+- a main-actor method waits on another path that also needs the main actor.
 
 ### Priority inversion
 
-If high-priority UI work is waiting on lower-priority work that holds a needed
-resource, the UI still feels hung even if the main thread stack looks shallow.
-
-## Fix patterns
-
-### Keep main-thread work small and deterministic
-
-Prefer this split:
-
-- main thread: input, state wiring, view invalidation
-- background work: parsing, formatting batches, image prep, persistence
-- main thread again: commit the final result
-
-### Precompute instead of recompute
-
-```swift
-// DON'T
-Text(distanceFormatter.string(from: trip.distance))
-
-// DO
-Text(trip.formattedDistance)
-```
-
-If the value changes rarely, compute it at the model boundary.
-
-### Stream results instead of blocking for all results
+When the UI waits for lower-priority work that holds a shared resource, the app
+feels hung even though the main thread's stack looks shallow.
 
-When practical, render partial state first and append or replace as work
-finishes.
+## Fix Patterns
 
-### Cancel stale work aggressively
-
-A common hang pattern is doing unnecessary work for content the user already
-navigated away from.
+- Divide the work: the main thread handles input, state wiring and
+  invalidation; background work does parsing, batch formatting, image
+  preparation and persistence; the main thread then commits the result.
+- Precompute values that rarely change where data enters the model, for
+  example `trip.formattedDistance` rather than formatting inside `Text`.
+- Deliver partial results as they arrive instead of waiting for everything.
+- Cancel work that is no longer wanted:
 
 ```swift
-.task(id: searchQuery) {
-    results = []
-    results = await search(query: searchQuery)
-}
+List(matches) { MatchRow(match: $0) }
+    .task(id: searchText) {
+        matches = (try? await catalog.search(searchText)) ?? []
+    }
 ```
 
-Pair this with cancellation inside the async work.
-
-## Verification checklist
-
-After a fix, confirm all of the following:
+`.task(id:)` cancels the previous task and starts a new one when `searchText`
+changes. Inside `search`, check `Task.isCancelled` or call
+`try Task.checkCancellation()` so abandoned searches stop early.
 
-- the same interaction no longer triggers a Hangs event
-- main-thread busy windows are shorter
-- the fix works in Release on device
-- repeated interaction does not regress frame pacing
-- cancellation works when navigating away mid-task
+## Verification
 
-If the hang disappears but scrolling or animation gets worse elsewhere, the
-work likely just moved rather than improved.
+- The same interaction no longer produces a Hangs event.
+- Main-thread busy windows are shorter.
+- It holds up in Release on a device.
+- Repeating the interaction does not degrade frame pacing.
+- Navigating away cancels the work.
 
-## Related SwiftUI implications
+If the hang is gone but scrolling or animation got worse, the work only moved.
 
-SwiftUI-specific hangs often come from:
+## What This Means for SwiftUI
 
-- long view body updates
-- broad observable dependencies
-- list identity churn
-- hidden work in formatting or filtering
+SwiftUI hangs usually come from long `body` updates, broad observable
+dependencies, identity churn in lists, or formatting and filtering hidden in
+views.
 
-Use the SwiftUI Instrument when the symptom is tied to view updates or layout.
-Use the Hangs instrument when the symptom is broad UI unresponsiveness and you
-first need to confirm the main thread is blocked.
+- The interaction is clearly tied to view updates or layout: start with the
+  SwiftUI Instrument.
+- The whole app is unresponsive and you first need proof the main thread is
+  blocked: start with the Hangs instrument.

package/pipeline/skills/shared/external/swiftui-performance/references/understanding-improving-swiftui-performance.md

@@ -1,177 +1,99 @@
-# Understanding and Improving SwiftUI Performance (Summary)
+# Long Updates and Frequent Updates
 
-Context: Apple guidance on diagnosing SwiftUI performance with Instruments and
-applying design patterns to reduce long or frequent updates.
+Based on Apple's article "Understanding and improving SwiftUI performance".
 
-## Contents
-- Core concepts
-- Instruments workflow
-- Reading SwiftUI timeline lanes
-- Diagnosing long updates
-- Diagnosing frequent updates
-- Common remediation patterns
-- Verification loop
-- Practical guardrails
+## Two Different Problems
 
-## Core concepts
+| Kind | What happens | Usual sources |
+|------|--------------|---------------|
+| Long updates | One update takes too long | An expensive `body`, layout, or hosted platform views |
+| Frequent updates | Many small updates add up | Dependency fan-out, noisy observable state, geometry or timer signals invalidating too much |
 
-SwiftUI is declarative. Performance problems are usually one of two categories:
+Both hurt, and they need different fixes. Treat them as separate bugs.
 
-- **Long updates**: one update takes too much time
-- **Frequent updates**: many small updates happen too often
+## Instruments Workflow
 
-Both feel bad to users, but they require different fixes.
+1. Build Release and run on a real device.
+2. Profile with the SwiftUI template.
+3. Repeat one interaction several times.
+4. Read the SwiftUI track first, then line it up with Time Profiler.
+5. Change one thing, record again.
 
-### Long updates
+A trace from an interaction you cannot reproduce on demand is much harder to
+interpret.
 
-These usually come from expensive body evaluation, expensive layout, or hosted
-platform-view work.
+## The Lanes
 
-### Frequent updates
+- **Update Groups**: batches of SwiftUI work.
+- **Long View Body Updates**: slow `body` evaluations.
+- **Long Platform View Updates**: slow hosted views. Check representables,
+  `List` rows that embed platform views, and media, map or web components.
+- **Other Long Updates**: layout, geometry and update coordination.
+- **Hitches**: missed frames. A hitch is a symptom; its cause may be elsewhere.
 
-These usually come from dependency fan-out, noisy observable state, or geometry
-and timer signals invalidating more of the tree than intended.
+## Diagnosing Long Updates
 
-## Instruments workflow
+Begin with the red or orange update, not with total runtime. Set the
+inspection range to it and look at the hottest frames in Time Profiler.
 
-A practical workflow:
-
-1. Profile in Release on a real device.
-2. Choose the SwiftUI template.
-3. Reproduce one interaction repeatedly.
-4. Inspect the SwiftUI track first, then correlate with Time Profiler.
-5. Change one thing at a time and re-record.
-
-If you cannot reproduce the exact interaction on demand, your trace will be much
-harder to interpret.
-
-## Reading SwiftUI timeline lanes
-
-### Update Groups
-
-Shows clusters of update activity over time. Good for spotting periods where the
-screen keeps re-evaluating even when no single event stands out.
-
-### Long View Body Updates
-
-Highlights expensive `body` work. These often point straight to code you can
-simplify or move out of render paths.
-
-### Long Platform View Updates
-
-Useful when SwiftUI hosts UIKit/AppKit content. If this lane is hot, inspect:
-
-- `UIViewRepresentable` / `UIViewControllerRepresentable`
-- `List` row content with embedded platform views
-- media, map, or web components
-
-### Other Long Updates
-
-Captures non-body SwiftUI work like layout, geometry, and update coordination.
-
-### Hitches
-
-Frame misses. These are the symptom users feel, not always the root cause.
-
-## Diagnosing long updates
-
-### Start with the red/orange update window
-
-Do not begin from total runtime. Begin from the expensive update itself.
-
-### Correlate with Time Profiler
-
-Set inspection range on the slow update and inspect hot frames.
-
-Common findings:
-
-- formatting in `body`
-- array transformations in `body`
-- image decoding during scroll
-- representable updates doing too much work every pass
-
-### Typical fix shape
+Typical findings:
+- formatting in `body`,
+- array transforms in `body`,
+- image decoding while scrolling,
+- representables doing too much on every update pass.
 
 ```swift
-// DON'T
-Text(Self.formatter.string(from: total as NSNumber) ?? "")
+// Formats on every evaluation.
+Text(order.total, format: .currency(code: order.currency))
 
-// DO
-Text(viewModel.formattedTotal)
+// Reads a value the model prepared when the total changed.
+Text(checkout.totalText)
 ```
 
-The right fix is usually architectural, not micro-optimizing the same body code.
-
-## Diagnosing frequent updates
-
-### Watch Update Groups and Cause Graph together
-
-Frequent updates often look like "the screen keeps waking up" rather than "one
-frame is red."
-
-### Look for noisy dependencies
-
-Typical offenders:
-
-- a timer injected high in the tree
-- geometry state stored in a shared model
-- a broad `@Observable` root model
-- environment values changing more often than needed
-
-### Reduce fan-out
-
-Good strategies:
-
-- split shared models by domain
-- move fast-changing state lower in the tree
-- derive narrow child state instead of passing whole parents
-- gate updates by thresholds when continuous values are noisy
-
-## Common remediation patterns
-
-### Precompute presentation values
-
-Cache strings, sorted arrays, and other display-ready values before render.
-
-### Make dependencies narrower
-
-A row should depend on row state, not screen state.
-
-### Keep representables idempotent
-
-Only touch hosted UIKit/AppKit views when actual inputs changed.
-
-### Avoid layout feedback loops
+The lasting fix is usually architectural: decide where derived values live.
 
-Be careful when geometry changes trigger state changes that trigger layout again.
+## Diagnosing Frequent Updates
 
-### Make lists identity-friendly
+This looks like a screen that keeps waking up. Watch Update Groups together
+with the Cause and Effect Graph.
 
-Use stable IDs, pre-filtered data, and consistent row counts.
+Noisy dependencies to look for:
+- a timer injected high in the tree,
+- geometry stored in a shared model,
+- one broad `@Observable` object at the root,
+- environment values that change often.
 
-## Verification loop
+Reduce the fan-out:
+- split models by domain,
+- move fast-changing state further down,
+- hand children narrow derived values,
+- apply a threshold to continuous values before storing them.
 
-After every performance change:
+## Remediation
 
-- record the same trace again
-- compare update counts
-- compare hitch frequency
-- compare the target lane you were trying to cool down
-- verify behavior still matches product requirements
+- Precompute display values such as strings and sorted arrays.
+- Rows depend on row state, not on screen state.
+- Representables update idempotently.
+- Avoid feedback loops where geometry updates state that changes layout that
+  changes geometry.
+- Keep lists identity-friendly: stable ids, data filtered beforehand, a row
+  count that does not fluctuate.
 
-Performance fixes can accidentally change animation timing, placeholder states,
-or navigation behavior. Verify the UX, not just the graph.
+## Verification
 
-## Practical guardrails
+Record the same interaction again and compare update counts, how often hitches
+occur, the lane you were targeting, and the behaviour of the product. Fixes can
+shift animation timing, placeholders or navigation, so check the experience as
+well as the numbers.
 
-Use these as default heuristics:
+## Guardrails
 
-- keep work out of `body`
-- prefer smaller dependency surfaces
-- cache display data near the model layer
-- avoid hidden per-row allocations in lists
-- profile Release builds, not just debug builds
-- treat frequent updates and long updates as different bugs
+- Keep work out of `body`.
+- Keep dependency surfaces small.
+- Cache display data close to the model.
+- No hidden allocations per row.
+- Profile Release builds.
+- Long updates and frequent updates are distinct bugs.
 
-When a screen still feels slow after obvious body cleanups, the next place to
-look is usually dependency fan-out, not isolated hot code.
+If the screen is still slow after `body` is clean, look at dependency fan-out
+next.

package/pipeline/skills/shared/external/swiftui-performance/references/wwdc-session-sources.md

@@ -1,27 +1,21 @@
-# WWDC Session Sources
-
-## Contents
-- Optimizing SwiftUI performance with Instruments
-- Demystify SwiftUI performance
-- Understanding and improving SwiftUI performance
-- Understanding hangs in your app
-
-## Optimizing SwiftUI performance with Instruments
-
-- Transcript: [https://sosumi.ai/videos/play/wwdc2025/306](https://sosumi.ai/videos/play/wwdc2025/306)
-- Use this when validating the newer SwiftUI Instrument workflow, Cause and Effect Graph usage, and Instruments 26-specific terminology.
-
-## Demystify SwiftUI performance
-
-- Transcript: [https://sosumi.ai/videos/play/wwdc2023/10160](https://sosumi.ai/videos/play/wwdc2023/10160)
-- Use this when checking SwiftUI dependency fan-out, identity rules, and list/table guidance.
-
-## Understanding and improving SwiftUI performance
-
-- Transcript: [https://sosumi.ai/videos/play/wwdc2024/10160](https://sosumi.ai/videos/play/wwdc2024/10160)
-- Use this when checking current SwiftUI Instrument lane names and remediation patterns.
-
-## Understanding hangs in your app
-
-- Transcript: [https://sosumi.ai/videos/play/wwdc2023/10248](https://sosumi.ai/videos/play/wwdc2023/10248)
-- Use this when checking main run loop and Hangs instrument guidance.
+# Apple Sources Behind This Skill
+
+Search for these by title in the Developer app or on developer.apple.com.
+Sessions are cited by title and year.
+
+| Source | Kind | Consult it for |
+|--------|------|----------------|
+| "Optimize SwiftUI performance with Instruments" (WWDC25) | Session | The SwiftUI Instrument workflow, the Cause and Effect Graph, Instruments 26 terminology |
+| "Demystify SwiftUI performance" (WWDC23) | Session | Dependency fan-out, identity, and guidance for lists and tables |
+| "Understanding and improving SwiftUI performance" | Xcode documentation article | Current lane names and remediation for long and frequent updates |
+| "Understanding hangs in your app" | Xcode documentation article | Hang thresholds, the main run loop, triage |
+| "Analyze hangs with Instruments" (WWDC23) | Session | Using the Hangs instrument on the main run loop |
+
+Which one to open:
+- A trace from Instruments 26 with SwiftUI lanes: the WWDC25 session.
+- Rows re-rendering, ids churning, a list that will not diff: the WWDC23
+  "Demystify" session.
+- Deciding whether a problem is a long update or a frequent one: the SwiftUI
+  performance article.
+- A freeze where you first need to prove the main thread is blocked: the hangs
+  article and the WWDC23 hangs session.