@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-performance/SKILL.md

@@ -1,477 +1,314 @@
 ---
 name: swiftui-performance
-description: "Audit and improve SwiftUI runtime performance: slow rendering, janky scrolling, high CPU or memory, excessive view updates, layout thrash, body cost, identity churn, lazy loading, Instruments profiling. Use when diagnosing a SwiftUI performance problem; for a symptom-first audit ending in a written report use swiftui-performance-audit."
+description: "SwiftUI performance: slow rendering, janky scrolling, high CPU/memory, excess updates, layout thrash, costly body, identity churn, lazy loading, Observation dependencies, Instruments profiling. Use when auditing, diagnosing or improving SwiftUI performance from code or a trace. Not for report-style audits (swiftui-performance-audit)."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # SwiftUI Performance
 
-Audit SwiftUI view performance end-to-end, from instrumentation and baselining to root-cause analysis and concrete remediation steps.
-
-## Contents
-
-- [Workflow Decision Tree](#workflow-decision-tree)
-- [1. Code-First Review](#1-code-first-review)
-- [2. Guide the User to Profile](#2-guide-the-user-to-profile)
-- [3. Analyze and Diagnose](#3-analyze-and-diagnose)
-- [4. Remediate](#4-remediate)
-- [Common Code Smells (and Fixes)](#common-code-smells-and-fixes)
-- [5. Verify](#5-verify)
-- [Outputs](#outputs)
-- [Instruments Profiling](#instruments-profiling)
-- [Identity and Lifetime](#identity-and-lifetime)
-- [Lazy Loading Patterns](#lazy-loading-patterns)
-- [State and Observation Optimization](#state-and-observation-optimization)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Workflow Decision Tree
-
-- If the user provides code, start with "Code-First Review."
-- If the user only describes symptoms, ask for minimal code/context, then do "Code-First Review."
-- If code review is inconclusive, go to "Guide the User to Profile" and ask for a trace or screenshots.
-
-## 1. Code-First Review
-
-Collect:
-- Target view/feature code.
-- Data flow: state, environment, observable models.
-- Symptoms and reproduction steps.
-
-Focus on:
-- View invalidation storms from broad state changes.
-- Unstable identity in lists (`id` churn, `UUID()` per render).
-- Top-level conditional view swapping (`if/else` returning different root branches).
-- Heavy work in `body` (formatting, sorting, image decoding).
-- Layout thrash (deep stacks, `GeometryReader`, preference chains).
-- Large images without downsampling or resizing.
-- Over-animated hierarchies (implicit animations on large trees).
-
-Provide:
-- Likely root causes with code references.
-- Suggested fixes and refactors.
-- If needed, a minimal repro or instrumentation suggestion.
-
-## 2. Guide the User to Profile
-
-Explain how to collect data with Instruments:
-- Use the SwiftUI template in Instruments.
-- Profile a **Release build** on a real device when possible.
-- Reproduce the exact interaction (scroll, navigation, animation).
-- Capture SwiftUI timeline and Time Profiler.
-- Export or screenshot the relevant lanes and the call tree.
-
-Ask for:
-- Trace export or screenshots of SwiftUI lanes + Time Profiler call tree.
-- Device/OS/build configuration.
-
-## 3. Analyze and Diagnose
-
-Prioritize likely SwiftUI culprits:
-- View invalidation storms from broad state changes.
-- Unstable identity in lists (`id` churn, `UUID()` per render).
-- Top-level conditional view swapping (`if/else` returning different root branches).
-- Heavy work in `body` (formatting, sorting, image decoding).
-- Layout thrash (deep stacks, `GeometryReader`, preference chains).
-- Large images without downsampling or resizing.
-- Over-animated hierarchies (implicit animations on large trees).
-
-Summarize findings with evidence from traces/logs.
-
-## 4. Remediate
-
-Apply targeted fixes:
-- Narrow state scope (`@State`/`@Observable` closer to leaf views).
-- Stabilize identities for `ForEach` and lists.
-- Move heavy work out of `body` (precompute, cache, `@State`).
-- Use `equatable()` or value wrappers for expensive subtrees.
-- Downsample images before rendering.
-- Reduce layout complexity or use fixed sizing where possible.
-
-## Common Code Smells (and Fixes)
-
-Look for these patterns during code review.
-
-### Expensive formatters in `body`
+Baseline: iOS 26 and Xcode 26. Observation needs iOS 17; APIs that need a
+later release say so.
 
-```swift
-var body: some View {
-    let number = NumberFormatter() // slow allocation
-    let measure = MeasurementFormatter() // slow allocation
-    Text(measure.string(from: .init(value: meters, unit: .meters)))
-}
-```
+A symptom-first audit whose deliverable is a written report belongs to
+`swiftui-performance-audit`. General LLDB and Instruments technique is in
+`debugging-instruments`.
 
-Prefer cached formatters in a model or a dedicated helper:
+## Where to Start
 
-```swift
-final class DistanceFormatter {
-    static let shared = DistanceFormatter()
-    let number = NumberFormatter()
-    let measure = MeasurementFormatter()
-}
-```
+| You have | Do this |
+|----------|---------|
+| The code | Start with the code review below |
+| Only a description of the symptom | Ask for the smallest amount of code and context that shows it, then review the code |
+| A code review that found nothing convincing | Walk the user through a profiling session and ask for the trace or screenshots |
 
-### Computed properties that do heavy work
+## 1. Review the Code
 
-```swift
-var filtered: [Item] {
-    items.filter { $0.isEnabled } // runs on every body eval
-}
-```
+Collect three things: the view or feature code, how data flows into it (state,
+environment, observable models), and the symptom with steps to reproduce.
 
-Prefer precompute or cache on change:
+Look for these, most frequent first:
 
-```swift
-@State private var filtered: [Item] = []
-// update filtered when inputs change
-```
+- A broad state change that invalidates far more views than it needs to.
+- List identity that is not stable: ids that change, a `UUID()` made during
+  render.
+- A root `if`/`else` that swaps between two different view trees.
+- Expensive work inside `body`: formatting, sorting, image decoding.
+- Layout thrash from deep stacks, `GeometryReader` or chains of preferences.
+- Large images shown without downsampling.
+- Implicit animations applied to large subtrees.
 
-### Sorting/filtering in `body` or `ForEach`
+Report the likely causes with references to the code, the fixes or refactors,
+and where useful a small repro or an instrumentation idea.
 
-```swift
-// DON'T: sorts or filters on every body evaluation
-ForEach(items.sorted(by: sortRule)) { item in Row(item) }
-ForEach(items.filter { $0.isEnabled }) { item in Row(item) }
-```
+## 2. Profile When Code Is Not Enough
 
-Prefer precomputed, cached collections with stable identity. Update on input change, not in `body`.
+Ask the user to:
 
-### Unstable identity
+1. Profile with the SwiftUI template in Instruments (Cmd+I).
+2. Use a Release build on a real device whenever possible.
+3. Repeat the exact interaction: the scroll, the push, the animation.
+4. Capture the SwiftUI lanes and Time Profiler, then export the trace or take
+   screenshots of the lanes and the call tree.
+5. Send those along with the device, OS version and build configuration.
 
-```swift
-ForEach(items, id: \.self) { item in
-    Row(item)
-}
-```
+The full lane-by-lane workflow is in
+[the SwiftUI Instrument guide](references/optimizing-swiftui-performance-instruments.md).
 
-Avoid `id: \.self` for non-stable values; use a stable ID.
+## 3. Diagnose
 
-### Top-level conditional view swapping
+Use the same list as the code review (broad invalidation, unstable identity,
+swapped roots, heavy bodies, layout thrash, oversized images, too much
+animation) and tie every conclusion to evidence from the trace or logs.
 
-```swift
-var content: some View {
-    if isEditing {
-        editingView
-    } else {
-        readOnlyView
-    }
-}
-```
+## 4. Fix
 
-Prefer one stable base view and localize conditions to sections/modifiers (for example inside `toolbar`, row content, `overlay`, or `disabled`). This reduces root identity churn and helps SwiftUI diffing stay efficient.
+- Move state closer to the leaves that read it (`@State`, `@Observable`).
+- Give `ForEach` and `List` identities that do not change.
+- Take heavy work out of `body`: compute once, cache, keep results in `@State`
+  or the model.
+- Put `equatable()` or a small value wrapper around expensive subtrees.
+- Downsample images before they reach the view.
+- Simplify layout, or use fixed sizes where the design allows.
 
-### Image decoding on the main thread
+### Smells and their fixes
 
 ```swift
-Image(uiImage: UIImage(data: data)!)
-```
-
-Prefer decode/downsample off the main thread and store the result.
-
-### Broad dependencies in observable models
-
-```swift
-@Observable class Model {
-    var items: [Item] = []
+struct FuelRow: View {
+    let litres: Double
+    var body: some View {
+        Text(FuelFormat.shared.string(from: litres as NSNumber) ?? "")
+    }
 }
 
-var body: some View {
-    Row(isFavorite: model.items.contains(item))
+enum FuelFormat {
+    static let shared: NumberFormatter = {
+        let formatter = NumberFormatter()
+        formatter.maximumFractionDigits = 1
+        return formatter
+    }()
 }
 ```
 
-Prefer granular view models or per-item state to reduce update fan-out.
-
-## 5. Verify
-
-Ask the user to re-run the same capture and compare with baseline metrics.
-Summarize the delta (CPU, frame drops, memory peak) if provided.
+Building a `NumberFormatter` or `MeasurementFormatter` in `body` costs time on
+every evaluation. Keep one cached instance as above, or use a `FormatStyle`.
 
-## Outputs
-
-Provide:
-- A short metrics table (before/after if available).
-- Top issues (ordered by impact).
-- Proposed fixes with estimated effort.
-
-## Instruments Profiling
-
-Use the **SwiftUI instrument template** in Xcode (Cmd+I to profile). Key instruments: SwiftUI View Body (body evaluation counts), SwiftUI View Properties (state change tracking), Time Profiler, and Hangs.
+```swift
+struct TripList: View {
+    let trips: [Trip]
+    let query: String
+    @State private var visible: [Trip] = []
 
-Add `Self._printChanges()` in debug builds to log which property triggered a view update:
+    var body: some View {
+        List(visible) { trip in
+            TripRow(trip: trip)
+        }
+        .onChange(of: trips, initial: true) { refresh() }
+        .onChange(of: query) { refresh() }
+    }
 
-```swift
-var body: some View {
-    #if DEBUG
-    let _ = Self._printChanges()  // "MyView: @self, _count changed."
-    #endif
-    Text("Count: \(count)")
+    private func refresh() {
+        visible = trips
+            .filter { query.isEmpty || $0.name.localizedStandardContains(query) }
+            .sorted { $0.departure < $1.departure }
+    }
 }
 ```
 
-See [references/optimizing-swiftui-performance-instruments.md](references/optimizing-swiftui-performance-instruments.md) for the full profiling workflow.
-
-## Identity and Lifetime
-
-### Structural Identity vs Explicit Identity
+A computed property that filters, or `ForEach(items.sorted(by:))` and
+`ForEach(items.filter { ... })`, redo the work on every evaluation. Keep the
+result in `@State` (or the model) and refresh it only when an input changes;
+the stored array also keeps identities stable.
 
-SwiftUI assigns every view an **identity** used to track its lifetime, state, and animations.
+| Smell | Fix |
+|-------|-----|
+| `ForEach(tags, id: \.self)` over values that can repeat or change | Use a stable identifier |
+| Root `if isEditing { EditorView() } else { ReaderView() }` | Keep one base view and put the condition inside sections, row content or modifiers (`toolbar`, `overlay`, `disabled`) |
+| `Image(uiImage: UIImage(data: data)!)` in `body` | Decode and downsample off the main thread, store the resulting image |
+| Every row reads `model.favorites.contains(item)` on one broad `@Observable` | Give rows per-item state or a narrower model so one change does not reach every row |
 
-- **Structural identity** (default): determined by the view's position in the view hierarchy. SwiftUI uses the call-site location in `body` to distinguish views.
-- **Explicit identity**: you assign with `.id(_:)` modifier or `ForEach(items, id: \.stableID)`.
-
-```swift
-// Structural identity: SwiftUI knows these are different views by position
-VStack {
-    Text("First")   // position 0
-    Text("Second")  // position 1
-}
-```
-
-### How Identity Tracks View Lifetime
+## 5. Verify
 
-When a view's identity changes, SwiftUI treats it as a **new view**:
+Ask the user to repeat the same capture and compare it with the first one:
+CPU, dropped frames and peak memory.
 
-- All `@State` is reset.
-- `onAppear` fires again.
-- Animations may restart.
-- Transition animations play (if defined).
+Deliver:
+- a short before and after metrics table,
+- the main issues ordered by impact,
+- the fixes with a rough effort estimate.
 
-When identity stays the same, SwiftUI updates the **existing view** in place, preserving state and providing smooth transitions.
+## Instruments
 
-### AnyView and Identity Reset
+Profile with Cmd+I and the SwiftUI template. In Instruments 26 the SwiftUI
+instrument shows lanes such as Update Groups, Long View Body Updates and the
+Cause and Effect Graph. Older Instruments versions offered separate SwiftUI
+View Body (how often bodies ran) and SwiftUI View Properties (which properties
+changed) instruments. Pair either with Time Profiler and Hangs.
 
-`AnyView` erases type information, forcing SwiftUI to fall back to less efficient diffing:
+To see why a particular view updated while debugging:
 
 ```swift
-// DON'T: AnyView destroys type identity
-func makeView(for item: Item) -> AnyView {
-    if item.isPremium {
-        return AnyView(PremiumRow(item: item))
-    } else {
-        return AnyView(StandardRow(item: item))
-    }
-}
-
-// DO: use @ViewBuilder to preserve structural identity
-@ViewBuilder
-func makeView(for item: Item) -> some View {
-    if item.isPremium {
-        PremiumRow(item: item)
-    } else {
-        StandardRow(item: item)
+struct ScoreBadge: View {
+    let score: Int
+    var body: some View {
+        #if DEBUG
+        let _ = Self._printChanges()
+        #endif
+        Text(score, format: .number)
     }
 }
 ```
 
-`AnyView` also prevents SwiftUI from detecting which branch changed, causing full subtree replacement instead of targeted updates.
-
-### Ternary Modifiers Preserve Structural Identity
-
-`if`/`else` in a view builder creates `_ConditionalContent`  -  two separate view branches with distinct identities. When the condition changes, SwiftUI destroys one branch and creates the other, resetting all `@State`.
-
-For toggling **modifiers** on the same view, use a ternary expression instead:
-
-```swift
-// DON'T: if/else creates two separate Text views with different identities
-if isHighlighted {
-    Text(title).foregroundStyle(.yellow)
-} else {
-    Text(title).foregroundStyle(.primary)
-}
+The console then prints lines such as `ScoreBadge: @self, _score changed.`.
 
-// DO: ternary keeps one Text view, just changes the modifier value
-Text(title)
-    .foregroundStyle(isHighlighted ? .yellow : .primary)
-```
+## Identity and Lifetime
 
-This preserves the view's identity (and its state) across the condition change, and SwiftUI can animate the transition smoothly.
+Every view has an identity. SwiftUI uses it to decide how long the view lives,
+which state belongs to it, and what to animate.
 
-Use `if`/`else` when the **view type itself** differs between branches. Use ternary when only a **property or modifier** changes.
+- **Structural identity** is the default: the view's type and position in the
+  hierarchy.
+- **Explicit identity** comes from `.id(_:)` or from the id in
+  `ForEach(items, id: \.code)`.
 
-### id() Modifier Impacts
+| Identity changed | Identity kept |
+|------------------|---------------|
+| All `@State` starts over | The view is updated in place |
+| `onAppear` runs again | State survives |
+| Animations can restart and transitions play | Changes animate smoothly |
 
-The `.id()` modifier assigns explicit identity. Changing the value **destroys and recreates** the view:
+`AnyView` hides the concrete type, so SwiftUI cannot tell which branch it is
+looking at and falls back to replacing the whole subtree. Return `some View`
+from a `@ViewBuilder` function instead:
 
 ```swift
-// DON'T: UUID() changes every render, destroying and recreating the view each time
-ScrollView {
-    LazyVStack {
-        ForEach(items) { item in
-            Row(item: item)
-                .id(UUID())  // kills performance -- new identity every render
-        }
+@ViewBuilder
+func statusView(for status: Shipment.Status) -> some View {
+    if status == .delivered {
+        Label("Delivered", systemImage: "checkmark.circle")
+    } else {
+        ProgressView(value: status.progress)
     }
 }
-
-// DO: use a stable identifier
-ForEach(items) { item in
-    Row(item: item)
-        .id(item.stableID)  // identity only changes when the item actually changes
-}
 ```
 
-Intentional `.id()` change is useful for **resetting state** (e.g., `.id(selectedTab)` to reset a scroll position when switching tabs).
-
-## Lazy Loading Patterns
-
-### LazyVStack and LazyHStack
-
-Lazy stacks only create views for items currently visible on screen. Off-screen items are not evaluated until scrolled into view.
+An `if`/`else` in a view builder produces `_ConditionalContent`: two separate
+identities. Flipping the condition throws one branch away together with its
+`@State`. When only a value changes, use a ternary so there is one view:
 
 ```swift
-ScrollView {
-    LazyVStack {
-        ForEach(items) { item in
-            ItemRow(item: item)
-        }
-    }
-}
+Image(systemName: "star.fill")
+    .foregroundStyle(isPinned ? .orange : .secondary)
 ```
 
-Key behaviors:
-- Views are created lazily but **not destroyed** when scrolled off screen (they remain in memory).
-- `onAppear` fires when the view first enters the visible area.
-- `onDisappear` fires when it leaves, but the view is still alive.
+Rule: `if`/`else` when the view type differs, a ternary when only a property or
+modifier value differs.
 
-### LazyVGrid and LazyHGrid
+Changing the value passed to `.id()` destroys the view and builds a new one.
+`.id(UUID())` on a row in a `LazyVStack` therefore creates a fresh identity on
+every render. Use `.id(item.code)`. Changing the id on purpose is fine when you
+want a reset, for example `.id(activeTab)` to start a scroll view at the top
+again after switching tabs.
 
-Use lazy grids for multi-column layouts:
+## Lazy Containers
 
-```swift
-// Adaptive: as many columns as fit with minimum width
-let columns = [GridItem(.adaptive(minimum: 150))]
+- `LazyVStack` and `LazyHStack` only build views that are on screen; the rest
+  are not evaluated until they scroll in.
+- A view built lazily is not destroyed when it scrolls away; it stays in
+  memory.
+- `onAppear` runs when a view first enters the visible area; `onDisappear` runs
+  when it leaves, while the view itself stays alive.
+- For several columns use `LazyVGrid` or `LazyHGrid`.
+  `GridItem(.adaptive(minimum: 150))` fits as many columns as the width
+  allows; three `GridItem(.flexible())` give three equal columns.
 
-ScrollView {
-    LazyVGrid(columns: columns) {
-        ForEach(photos) { photo in
-            PhotoThumbnail(photo: photo)
-        }
-    }
+```swift
+LazyVGrid(columns: [GridItem(.adaptive(minimum: 150))]) {
+    ForEach(albums) { AlbumTile(album: $0) }
 }
-
-// Fixed: exact number of equal columns
-let fixedColumns = [
-    GridItem(.flexible()),
-    GridItem(.flexible()),
-    GridItem(.flexible()),
-]
 ```
 
-### When to Use Lazy vs Eager Stacks
-
-| Scenario | Use |
-|----------|-----|
-| < 50 items | `VStack` / `HStack` (eager is fine) |
-| 50-100 items | Either works; prefer `Lazy` if items are complex |
-| > 100 items | `LazyVStack` / `LazyHStack` (required for performance) |
-| Always-visible content | `VStack` (no benefit to lazy) |
-| Scrollable lists | `LazyVStack` inside `ScrollView`, or `List` |
-
-**Important:** Do not nest `GeometryReader` inside lazy containers. It forces eager measurement and defeats lazy loading. Use `.onGeometryChange` (iOS 16+) instead.
+| Content | Container |
+|---------|-----------|
+| Fewer than about 50 items | `VStack` or `HStack` is fine |
+| 50 to 100 items | Either; prefer lazy when rows are complex |
+| More than 100 items | `LazyVStack` or `LazyHStack` |
+| Always fully visible | `VStack`; laziness gains nothing |
+| A scrolling list | `LazyVStack` inside `ScrollView`, or `List` |
 
-## State and Observation Optimization
+Do not put `GeometryReader` inside lazy content: it makes SwiftUI measure
+eagerly. Use `.onGeometryChange(for:of:action:)`, which is available back to
+iOS 16 when building with the Xcode 16 SDK or later.
 
-### `@Observable` Granular Tracking
+## Observation
 
-`@Observable` (Observation framework, iOS 17+) tracks property access at the **per-property level**. A view only re-evaluates when properties it actually read in `body` change:
+With `@Observable` (iOS 17), SwiftUI records which properties a `body` reads
+and re-evaluates the view only when one of those changes.
 
 ```swift
-@Observable class UserProfile {
-    var name: String = ""
+@Observable
+final class Profile {
+    var displayName = ""
+    var biography = ""
     var avatarURL: URL?
-    var biography: String = ""
 }
 
-// This view ONLY re-renders when `name` changes -- not when
-// biography or avatarURL change, because it only reads `name`
-struct NameLabel: View {
-    let profile: UserProfile
+struct ProfileHeader: View {
+    let profile: Profile
     var body: some View {
-        Text(profile.name)
+        Text(profile.displayName)
     }
 }
 ```
 
-This is a significant improvement over `ObservableObject` + `@Published`, which invalidates all observing views when **any** published property changes.
+`ProfileHeader` ignores changes to `biography` and `avatarURL`. With
+`ObservableObject`, any `@Published` change invalidates every observer.
 
-### Avoiding Observation Scope Pollution
+A single body that reads many properties still has a wide dependency surface.
+Split it into children that each read what they show: a name row, an email row,
+an avatar view, a settings form.
 
-If a view reads many properties from an `@Observable` model in `body`, it re-renders when **any** of those properties change. Push reads into child views to narrow the scope:
+Computed properties derive values without widening the surface:
 
 ```swift
-// DON'T: reads name, email, avatar, and settings in one body
-struct ProfileView: View {
-    let model: ProfileModel
-    var body: some View {
-        VStack {
-            Text(model.name)           // tracks name
-            Text(model.email)          // tracks email
-            AsyncImage(url: model.avatar) // tracks avatar
-            SettingsForm(model.settings)  // tracks settings
-        }
-    }
-}
-
-// DO: split into child views so each only tracks what it reads
-struct ProfileView: View {
-    let model: ProfileModel
-    var body: some View {
-        VStack {
-            NameRow(model: model)      // only tracks name
-            EmailRow(model: model)     // only tracks email
-            AvatarView(model: model)   // only tracks avatar
-            SettingsForm(model: model) // only tracks settings
-        }
-    }
+@Observable
+final class Basket {
+    var lines: [BasketLine] = []
+    var total: Decimal { lines.reduce(0) { $0 + $1.price * Decimal($1.quantity) } }
 }
 ```
 
-### Computed Properties for Derived State
-
-Use computed properties on `@Observable` models to derive state without introducing extra stored properties that widen observation scope:
-
-```swift
-@Observable class ShoppingCart {
-    var items: [CartItem] = []
-
-    // Views reading `total` only re-render when `items` changes
-    var total: Decimal {
-        items.reduce(0) { $0 + $1.price * Decimal($1.quantity) }
-    }
-}
-```
+A view that reads `total` updates only when `lines` changes.
 
 ## Common Mistakes
 
-1. **Profiling Debug builds.** Debug builds include extra runtime checks and disable optimizations, producing misleading perf data. Profile Release builds on a real device.
-2. **Observing an entire model when only one property is needed.** Break large `@Observable` models into focused ones, or use computed properties/closures to narrow observation scope.
-3. **Using `GeometryReader` inside ScrollView items.** GeometryReader forces eager sizing and defeats lazy loading. Prefer `.onGeometryChange` (iOS 16+) or measure outside the lazy container.
-4. **Calling `DateFormatter()` or `NumberFormatter()` inside `body`.** These are expensive to create. Make them static or move them outside the view.
-5. **Animating non-equatable state.** If SwiftUI cannot determine equality, it redraws every frame. Conform state to `Equatable`, then use `.animation(_:value:)` for simple value-bound changes or `.animation(_:body:)` for narrower modifier-scoped implicit animation.
-6. **Large flat `List` without identifiers.** Use `id:` or make items `Identifiable` so SwiftUI can diff efficiently instead of rebuilding the entire list.
-7. **Unnecessary `@State` wrapper objects.** Wrapping a simple value type in a class for `@State` defeats value semantics. Use plain `@State` with structs.
-8. **Blocking `MainActor` with synchronous I/O.** File reads, JSON parsing of large payloads, and image decoding should happen off the main actor. Use `Task.detached` or a custom actor.
+| Mistake | Better |
+|---------|--------|
+| Profiling a Debug build (extra checks, no optimisation) | Profile Release on a device |
+| Observing a whole model to show one field | Split the model, or pass a computed value or closure |
+| `GeometryReader` inside `ScrollView` rows | `.onGeometryChange`, or measure outside the lazy content |
+| `DateFormatter()` or `NumberFormatter()` in `body` | A static instance or a `FormatStyle` |
+| Animating state that is not `Equatable`, so every frame redraws | Make it `Equatable`; use `.animation(_:value:)`, or `.animation(_:body:)` (iOS 17) to limit the animation to specific modifiers |
+| A large `List` without identifiers | `Identifiable` data or `id:` |
+| Wrapping a struct in a class to hold it in `@State` | Store the struct in `@State` directly |
+| Reading files, big JSON or images synchronously on the main actor | A `@concurrent` async function (Swift 6.2), a dedicated actor, or `Task.detached` |
 
 ## Review Checklist
 
-- [ ] No `DateFormatter`/`NumberFormatter` allocations inside `body`
-- [ ] Large lists use `Identifiable` items or explicit `id:`
-- [ ] `@Observable` models expose only the properties views actually read
-- [ ] Heavy computation is off `MainActor` (image processing, parsing)
-- [ ] `GeometryReader` is not inside a `LazyVStack`/`LazyHStack`/`List`
-- [ ] Implicit animations use `.animation(_:value:)` for value-bound changes or `.animation(_:body:)` for narrower modifier scope
-- [ ] No synchronous network/file I/O on the main thread
-- [ ] Profiling done on Release build, real device
-- [ ] `@Observable` view models are `@MainActor`-isolated; types crossing concurrency boundaries are `Sendable`
+- [ ] No formatters created in `body`
+- [ ] Large lists use `Identifiable` data or an explicit `id:`
+- [ ] `@Observable` models expose what views actually read, nothing broader
+- [ ] Heavy computation runs off the main actor
+- [ ] No `GeometryReader` inside `LazyVStack`, `LazyHStack` or `List`
+- [ ] Implicit animations use `.animation(_:value:)` or `.animation(_:body:)`
+- [ ] No synchronous network or file I/O on the main thread
+- [ ] Profiling done in Release on a real device
+- [ ] `@Observable` view models are `@MainActor`; types that cross isolation are `Sendable`
 
 ## References
 
-- Demystify SwiftUI performance (WWDC23): [references/demystify-swiftui-performance-wwdc23.md](references/demystify-swiftui-performance-wwdc23.md)
-- Optimizing SwiftUI performance with Instruments: [references/optimizing-swiftui-performance-instruments.md](references/optimizing-swiftui-performance-instruments.md)
-- Understanding hangs in your app: [references/understanding-hangs-in-your-app.md](references/understanding-hangs-in-your-app.md)
-- Understanding and improving SwiftUI performance: [references/understanding-improving-swiftui-performance.md](references/understanding-improving-swiftui-performance.md)
-- WWDC transcript sources: [references/wwdc-session-sources.md](references/wwdc-session-sources.md)
+- [Mental model, dependencies and identity](references/demystify-swiftui-performance-wwdc23.md)
+- [Profiling with the SwiftUI Instrument](references/optimizing-swiftui-performance-instruments.md)
+- [Hangs and the main run loop](references/understanding-hangs-in-your-app.md)
+- [Long versus frequent updates](references/understanding-improving-swiftui-performance.md)
+- [Which Apple session or article to consult](references/wwdc-session-sources.md)