@mmerterden/multi-agent-pipeline 8.6.2 → 10.0.6

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

@@ -1,52 +1,177 @@
 # Understanding and Improving SwiftUI Performance (Summary)
 
-Context: Apple guidance on diagnosing SwiftUI performance with Instruments and applying design patterns to reduce long or frequent updates.
+Context: Apple guidance on diagnosing SwiftUI performance with Instruments and
+applying design patterns to reduce long or frequent updates.
+
+## Contents
+- Core concepts
+- Instruments workflow
+- Reading SwiftUI timeline lanes
+- Diagnosing long updates
+- Diagnosing frequent updates
+- Common remediation patterns
+- Verification loop
+- Practical guardrails
 
 ## Core concepts
 
-- SwiftUI is declarative; view updates are driven by state, environment, and observable data dependencies.
-- View bodies must compute quickly to meet frame deadlines; slow or frequent updates lead to hitches.
-- Instruments is the primary tool to find long-running updates and excessive update frequency.
+SwiftUI is declarative. Performance problems are usually one of two categories:
+
+- **Long updates**: one update takes too much time
+- **Frequent updates**: many small updates happen too often
+
+Both feel bad to users, but they require different fixes.
+
+### Long updates
+
+These usually come from expensive body evaluation, expensive layout, or hosted
+platform-view work.
+
+### Frequent updates
+
+These usually come from dependency fan-out, noisy observable state, or geometry
+and timer signals invalidating more of the tree than intended.
 
 ## Instruments workflow
 
-1. Profile via Product > Profile.
-2. Choose the SwiftUI template and record.
-3. Exercise the target interaction.
-4. Stop recording and inspect the SwiftUI track + 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
+
+```swift
+// DON'T
+Text(Self.formatter.string(from: total as NSNumber) ?? "")
+
+// DO
+Text(viewModel.formattedTotal)
+```
+
+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
+
+Be careful when geometry changes trigger state changes that trigger layout again.
 
-## SwiftUI timeline lanes
+### Make lists identity-friendly
 
-- Update Groups: overview of time SwiftUI spends calculating updates.
-- Long View Body Updates: orange >500us, red >1000us.
-- Long Platform View Updates: AppKit/UIKit hosting in SwiftUI.
-- Other Long Updates: geometry/text/layout and other SwiftUI work.
-- Hitches: frame misses where UI wasn't ready in time.
+Use stable IDs, pre-filtered data, and consistent row counts.
 
-## Diagnose long view body updates
+## Verification loop
 
-- Expand the SwiftUI track; inspect module-specific subtracks.
-- Set Inspection Range and correlate with Time Profiler.
-- Use call tree or flame graph to identify expensive frames.
-- Repeat the update to gather enough samples for analysis.
-- Filter to a specific update (Show Calls Made by `MySwiftUIView.body`).
+After every performance change:
 
-## Diagnose frequent updates
+- 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
 
-- Use Update Groups to find long active groups without long updates.
-- Set inspection range on the group and analyze update counts.
-- Use Cause graph ("Show Causes") to see what triggers updates.
-- Compare causes with expected data flow; prioritize the highest-frequency causes.
+Performance fixes can accidentally change animation timing, placeholder states,
+or navigation behavior. Verify the UX, not just the graph.
 
-## Remediation patterns
+## Practical guardrails
 
-- Move expensive work out of `body` and cache results.
-- Use `Observable()` macro to scope dependencies to properties actually read.
-- Avoid broad dependencies that fan out updates to many views.
-- Reduce layout churn; isolate state-dependent subtrees from layout readers.
-- Avoid storing closures that capture parent state; precompute child views.
-- Gate frequent updates (e.g., geometry changes) by thresholds.
+Use these as default heuristics:
 
-## Verification
+- 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
 
-- Re-record after changes to confirm reduced update counts and fewer hitches.
+When a screen still feels slow after obvious body cleanups, the next place to
+look is usually dependency fan-out, not isolated hot code.

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

@@ -0,0 +1,27 @@
+# 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.

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

@@ -15,7 +15,7 @@ Review process:
 1. Check that views, modifiers, and animations have been written optimally using `references/views.md`.
 1. Validate that data flow is configured correctly using `references/data.md`.
 1. Ensure navigation is updated and performant using `references/navigation.md`.
-1. Ensure the code uses designs that are accessible and compliant with Apple’s Human Interface Guidelines using `references/design.md`.
+1. Ensure the code uses designs that are accessible and compliant with Apple's Human Interface Guidelines using `references/design.md`.
 1. Validate accessibility compliance including Dynamic Type, VoiceOver, and Reduce Motion using `references/accessibility.md`.
 1. Ensure the code is able to run efficiently using `references/performance.md`.
 1. Quick validation of Swift code using `references/swift.md`.
@@ -99,7 +99,7 @@ End of example.
 
 - `references/accessibility.md` - Dynamic Type, VoiceOver, Reduce Motion, and other accessibility requirements.
 - `references/api.md` - updating code for modern API, and the deprecated code it replaces.
-- `references/design.md` - guidance for building accessible apps that meet Apple’s Human Interface Guidelines.
+- `references/design.md` - guidance for building accessible apps that meet Apple's Human Interface Guidelines.
 - `references/hygiene.md` - making code compile cleanly and be maintainable in the long term.
 - `references/navigation.md` - navigation using `NavigationStack`/`NavigationSplitView`, plus alerts, confirmation dialogs, and sheets.
 - `references/performance.md` - optimizing SwiftUI code for maximum performance.

package/pipeline/skills/shared/external/swiftui-pro/references/accessibility.md

@@ -1,13 +1,13 @@
 # Accessibility
 
-- Respect the user’s accessibility settings for fonts, colors, animations, and more.
+- Respect the user's accessibility settings for fonts, colors, animations, and more.
 - Do not force specific font sizes. Prefer Dynamic Type (`.font(.body)`, `.font(.headline)`, etc.).
 - If you *need* a custom font size, use `@ScaledMetric` when targeting iOS 18 and earlier. When targeting iOS 26 or later, `.font(.body.scaled(by:))` is also available to get font size adjustment.
 - Flag instances where images have unclear or unhelpful VoiceOver readings, e.g. `Image(.newBanner2026)`. If they are decorative, suggest using `Image(decorative:)` or `accessibilityHidden()`, otherwise attach an `accessibilityLabel()`.
-- If the user has “Reduce Motion” enabled, replace large, motion-based animations with opacity instead.
-- If buttons have complex or frequently changing labels, recommend using `accessibilityInputLabels()` to provide better Voice Control commands. For example, if a button had a live-updating share price for Apple such as “AAPL $271.68”, adding an input label for “Apple” would be a big improvement.
+- If the user has "Reduce Motion" enabled, replace large, motion-based animations with opacity instead.
+- If buttons have complex or frequently changing labels, recommend using `accessibilityInputLabels()` to provide better Voice Control commands. For example, if a button had a live-updating share price for Apple such as "AAPL $271.68", adding an input label for "Apple" would be a big improvement.
 - Buttons with image labels must always include text, even if the text is invisible: `Button("Label", systemImage: "plus", action: myAction)`. Flag icon-only buttons that lack a text label as being bad for VoiceOver.
-- If color is an important differentiator in the user interface, make sure to respect the environment’s `.accessibilityDifferentiateWithoutColor` setting by showing some kind of variation beyond just color – icons, patterns, strokes, etc.
+- If color is an important differentiator in the user interface, make sure to respect the environment's `.accessibilityDifferentiateWithoutColor` setting by showing some kind of variation beyond just color - icons, patterns, strokes, etc.
 - The same is true of `Menu`: using `Menu("Options", systemImage: "ellipsis.circle") { }` is much better than just using an image.
 - Never use `onTapGesture()` unless you specifically need tap location or tap count. All other tappable elements should be a `Button`.
 - If `onTapGesture()` must be used, make sure to add `.accessibilityAddTraits(.isButton)` or similar so it can be read by VoiceOver correctly.

package/pipeline/skills/shared/external/swiftui-pro/references/api.md

@@ -36,4 +36,4 @@ Text("\(red)\(blue)")
 
 ## Using ObservableObject
 
-If using `ObservableObject` is absolutely required – for example if you are trying to create a debouncer using a Combine publisher – you should always make sure `import Combine` is added. This was previously provided through SwiftUI, but that is no longer the case.
+If using `ObservableObject` is absolutely required - for example if you are trying to create a debouncer using a Combine publisher - you should always make sure `import Combine` is added. This was previously provided through SwiftUI, but that is no longer the case.

package/pipeline/skills/shared/external/swiftui-pro/references/data.md

@@ -15,7 +15,7 @@ These rules help ensure code is efficient and works well in the long term.
 ## Local state
 
 - `@State` should be marked `private` and only owned by the view that created it.
-- If a view stores a class instance that contains expensive-to-recompute data, e.g. `CIContext`, it can be stored using `@State` even though it is not an observable object. This effectively uses `@State` as a cache – storing something persistently, but not doing any change tracking on it since it's not an observable object.
+- If a view stores a class instance that contains expensive-to-recompute data, e.g. `CIContext`, it can be stored using `@State` even though it is not an observable object. This effectively uses `@State` as a cache - storing something persistently, but not doing any change tracking on it since it's not an observable object.
 
 
 ## Bindings
@@ -27,7 +27,7 @@ These rules help ensure code is efficient and works well in the long term.
 ## Working with data
 
 - Prefer to make structs conform to `Identifiable` rather than using `id: \.someProperty` in SwiftUI code.
-- Never attempt to use `@AppStorage` inside an `@Observable` class, even if marked `@ObservationIgnored` – it will *not* trigger view updates when a change happens.
+- Never attempt to use `@AppStorage` inside an `@Observable` class, even if marked `@ObservationIgnored` - it will *not* trigger view updates when a change happens.
 
 
 ## SwiftData

package/pipeline/skills/shared/external/swiftui-pro/references/design.md

@@ -2,24 +2,24 @@
 
 ## Creating a uniform design in this app
 
-Prefer to place standard fonts, sizes, colors, stack spacing, padding, rounding, animation timings, and more into a shared enum of constants, so they can be used by all views. This allows the app’s design to feel uniform and consistent, and be adjusted easily.
+Prefer to place standard fonts, sizes, colors, stack spacing, padding, rounding, animation timings, and more into a shared enum of constants, so they can be used by all views. This allows the app's design to feel uniform and consistent, and be adjusted easily.
 
 
 ## Requirements for flexible, accessible design
 
 - Never use `UIScreen.main.bounds` to read available space; prefer alternatives such as `containerRelativeFrame()`, or `visualEffect()` as appropriate, or (if there is no alternative) `GeometryReader`.
 - Prefer to avoid fixed frames for views unless content can fit neatly inside; this can cause problems across different device sizes, different Dynamic Type settings, and more. Giving frames some flexibility is usually preferred.
-- Apple’s minimum acceptable tap area for interactions on iOS is 44x44. Ensure this is strictly enforced.
+- Apple's minimum acceptable tap area for interactions on iOS is 44x44. Ensure this is strictly enforced.
 
 
 ## Standard system styling
 
 - Strongly prefer to use `ContentUnavailableView` when data is missing or empty, rather than designing something custom.
-- When using `searchable()`, you can show empty results using `ContentUnavailableView.search` and it will include the search term they used automatically – there’s no need to use `ContentUnavailableView.search(text: searchText)` or similar.
+- When using `searchable()`, you can show empty results using `ContentUnavailableView.search` and it will include the search term they used automatically - there's no need to use `ContentUnavailableView.search(text: searchText)` or similar.
 - If you need an icon and some text placed horizontally side by side, prefer `Label` over `HStack`.
 - Prefer system hierarchical styles (e.g. secondary/tertiary) over manual opacity when possible, so the system can adapt to the correct context automatically.
 - When using `Form`, wrap controls such as `Slider` in `LabeledContent` so the title and control are laid out correctly.
-- When using `RoundedRectangle`, the default rounding style is `.continuous` – there is no need to specify it explicitly.
+- When using `RoundedRectangle`, the default rounding style is `.continuous` - there is no need to specify it explicitly.
 
 
 ## Ensuring designs work for everyone

package/pipeline/skills/shared/external/swiftui-pro/references/hygiene.md

@@ -5,5 +5,5 @@
 - Unit tests should exist for core application logic. UI tests only where unit tests are not possible.
 - `@AppStorage` must never be used to store usernames, passwords, or other sensitive data. Use the keychain for that.
 - If SwiftLint is configured, it should return no warnings or errors.
-- If the project uses Localizable.xcstrings, prefer to add user-facing strings using symbol keys (e.g. “helloWorld”) in the string catalog with `extractionState` set to "manual", accessing them via generated symbols such as `Text(.helloWorld)`. Offer to translate new keys into all languages supported by the project.
-- If the Xcode MCP is configured, prefer its tools over generic alternatives. For example, `RenderPreview` is able to capture images of rendered SwiftUI previews for examination, and `DocumentationSearch` can search Apple’s documentation for latest usage instructions.
+- If the project uses Localizable.xcstrings, prefer to add user-facing strings using symbol keys (e.g. "helloWorld") in the string catalog with `extractionState` set to "manual", accessing them via generated symbols such as `Text(.helloWorld)`. Offer to translate new keys into all languages supported by the project.
+- If the Xcode MCP is configured, prefer its tools over generic alternatives. For example, `RenderPreview` is able to capture images of rendered SwiftUI previews for examination, and `DocumentationSearch` can search Apple's documentation for latest usage instructions.

package/pipeline/skills/shared/external/swiftui-pro/references/navigation.md

@@ -9,6 +9,6 @@
 ## Alerts, confirmation dialogs, and sheets
 
 - Always attach `confirmationDialog()` to the user interface that triggers the dialog. This allows Liquid Glass animations to move from the correct source.
-- If an alert has only a single “OK” button that does nothing but dismiss the alert, it can be omitted entirely: `.alert("Dismiss Me", isPresented: $isShowingAlert) { }`.
+- If an alert has only a single "OK" button that does nothing but dismiss the alert, it can be omitted entirely: `.alert("Dismiss Me", isPresented: $isShowingAlert) { }`.
 - If a sheet is designed to present an optional piece of data, prefer `sheet(item:)` over `sheet(isPresented:)` so the optional is safely unwrapped.
 - When using `sheet(item:)` with a view that accepts the item as its only initializer parameter, prefer `sheet(item: $someItem, content: SomeView.init)` over `sheet(item: $someItem) { someItem in SomeView(item: someItem) }`.

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

@@ -5,7 +5,7 @@
 - If a `ScrollView` has an opaque, static, and solid background, prefer to use `scrollContentBackground(.visible)` to improve scroll-edge rendering efficiency.
 - It is more efficient to break views up by making dedicated SwiftUI views rather than place them into computed properties or methods. Using `@ViewBuilder` on a property or method does not solve this; breaking views up is strongly preferred.
 - Always ensure view initializers are kept as small and simple as possible, avoiding any non-trivial work. Flag any work that can be moved into a `task()` modifier to be run when the view is shown.
-- Similarly, assume each view’s `body` property is called frequently – if logic such as sorting or filtering can be moved out of there easily, it should be.
+- Similarly, assume each view's `body` property is called frequently - if logic such as sorting or filtering can be moved out of there easily, it should be.
 - Avoid creating properties to store formatters such as `DateFormatter` unless they are required. A more natural approach is to use `Text` with a format, like this: `Text(Date.now, format: .dateTime.day().month().year())` or `Text(100, format: .currency(code: "USD"))`.
 - Avoid expensive inline transforms in `List`/`ForEach` initializers (e.g. `items.filter { ... }`) when they are repeated often.
 - Prefer deriving transformed data from the source-of-truth using `let`, or caching in `@State`. However, do not cache derived collections in `@State` unless you also own explicit invalidation logic to avoid stale UI.

package/pipeline/skills/shared/external/swiftui-pro/references/swift.md

@@ -9,10 +9,10 @@
 - Strongly prefer `Double` over `CGFloat`, except when using optionals or `inout`; Swift is able to bridge the two freely except in those two cases.
 - If you want to count array objects that match a predicate, always use `count(where:)` rather than `filter()` followed by `count`.
 - Prefer `Date.now` over `Date()` for clarity.
-- When `import SwiftUI` is already in a file, you do not need to add `import UIKit` or `import AppKit` to access things like `UIImage` or `NSImage` – they are imported automatically on the appropriate platform.
+- When `import SwiftUI` is already in a file, you do not need to add `import UIKit` or `import AppKit` to access things like `UIImage` or `NSImage` - they are imported automatically on the appropriate platform.
 - When dealing with the names of people, strongly prefer to use `PersonNameComponents` with modern formatting over simple string interpolation such as `Text("\(firstName) \(lastName)")`.
 - If a given type of data is repeatedly sorted using an identical closure, e.g. `books.sorted { $0.author < $1.author }`, prefer to make the type in question conform to `Comparable` so the sort order is centralized.
-- Prefer to avoid manual date formatting strings if possible. If manual date formatting *is* used for user display, at least make sure to use “y” rather than “yyyy” for years, so the year value is correct in all localizations. If the purpose is data exchange with an API, this rule does not apply.
+- Prefer to avoid manual date formatting strings if possible. If manual date formatting *is* used for user display, at least make sure to use "y" rather than "yyyy" for years, so the year value is correct in all localizations. If the purpose is data exchange with an API, this rule does not apply.
 - When trying to convert a string to a date, prefer the modern `Date` initializer API such as `Date(myString, strategy: .iso8601)`.
 - Flag instances where errors triggered by a user action are swallowed silently, e.g. using `print(error.localizedDescription)` rather than showing an alert or similar.
 - Prefer `if let value {` shorthand over `if let value = value {`.

package/pipeline/skills/shared/external/swiftui-pro/references/views.md

@@ -11,12 +11,12 @@
 - When rendering SwiftUI views to images, strongly prefer `ImageRenderer` over `UIGraphicsImageRenderer`.
 - `#Preview` should be used for previews, not the legacy `PreviewProvider` protocol.
 - When using `TabView(selection:)`, use a binding to a property that stores an enum rather than an integer or string. For example, `Tab("Home", systemImage: "house", value: .home)` is better than `Tab("Home", systemImage: "house", value: 0)`.
-- Strongly prefer to avoid breaking up view bodies using computed properties or methods that return `some View`, even if `@ViewBuilder` is used. Extract them into separate `View` structs instead, placing each into its own file. (Yes, this is repeated, but it’s so important it needs to be mentioned twice.)
+- Strongly prefer to avoid breaking up view bodies using computed properties or methods that return `some View`, even if `@ViewBuilder` is used. Extract them into separate `View` structs instead, placing each into its own file. (Yes, this is repeated, but it's so important it needs to be mentioned twice.)
 
 
 ## Animating views
 
-- Strongly prefer to use the `@Animatable` macro over creating `animatableData` manually – the macro automatically adds conformance to the `Animatable` protocol and creates the correct `animatableData` property. If some properties should not or cannot be animated (e.g. Booleans, integers, etc), mark them `@AnimatableIgnored`.
+- Strongly prefer to use the `@Animatable` macro over creating `animatableData` manually - the macro automatically adds conformance to the `Animatable` protocol and creates the correct `animatableData` property. If some properties should not or cannot be animated (e.g. Booleans, integers, etc), mark them `@AnimatableIgnored`.
 - Never use `animation(_ animation: Animation?)`; always provide a value to watch, such as `.animation(.bouncy, value: score)`.
 - Chaining animations must be done using a `completion` closure passed to `withAnimation()`, rather than trying to execute multiple `withAnimation()` calls using delays.
 

package/pipeline/skills/shared/external/swiftui-ui-patterns/SKILL.md

@@ -86,7 +86,7 @@ Choose the ownership location first, then pick the wrapper. Do not introduce a r
 3. Sketch the view hierarchy, routing model, and presentation points; extract repeated parts into subviews. For complex navigation, read `references/navigationstack.md`, `references/sheets.md`, or `references/deeplinks.md`. **Build and verify no compiler errors before proceeding.**
 4. Implement async loading with `.task` or `.task(id:)`, plus explicit loading and error states when needed. Read `references/async-state.md` when the work depends on changing inputs or cancellation.
 5. Add previews for the primary and secondary states, then add accessibility labels or identifiers when the UI is interactive. Read `references/previews.md` when the view needs fixtures or injected mock dependencies.
-6. Validate with a build: confirm no compiler errors, check that previews render without crashing, ensure state changes propagate correctly, and sanity-check that list identity and observation scope will not cause avoidable re-renders. Read `references/performance.md` if the screen is large, scroll-heavy, or frequently updated. For common SwiftUI compilation errors — missing `@State` annotations, ambiguous `ViewBuilder` closures, or mismatched generic types — resolve them before updating callsites. **If the build fails:** read the error message carefully, fix the identified issue, then rebuild before proceeding to the next step. If a preview crashes, isolate the offending subview, confirm its state initialisation is valid, and re-run the preview before continuing.
+6. Validate with a build: confirm no compiler errors, check that previews render without crashing, ensure state changes propagate correctly, and sanity-check that list identity and observation scope will not cause avoidable re-renders. Read `references/performance.md` if the screen is large, scroll-heavy, or frequently updated. For common SwiftUI compilation errors  -  missing `@State` annotations, ambiguous `ViewBuilder` closures, or mismatched generic types  -  resolve them before updating callsites. **If the build fails:** read the error message carefully, fix the identified issue, then rebuild before proceeding to the next step. If a preview crashes, isolate the offending subview, confirm its state initialisation is valid, and re-run the preview before continuing.
 
 ## Component references
 

package/pipeline/skills/shared/external/swiftui-uikit-interop/SKILL.md

@@ -5,9 +5,9 @@ description: "Bridges UIKit and SwiftUI by wrapping UIKit views and view control
 
 # SwiftUI-UIKit Interop
 
-Bridge UIKit and SwiftUI in both directions. Wrap UIKit views and view controllers for use in SwiftUI, embed SwiftUI views inside UIKit screens, and synchronize state across the boundary. Targets iOS 26+ with Swift 6.2 patterns; notes backward-compatible to iOS 16 unless stated otherwise.
+Bridge UIKit and SwiftUI in both directions. Wrap UIKit views and view controllers for use in SwiftUI, embed SwiftUI views inside UIKit screens, and synchronize state across the boundary. Targets iOS 26+ with Swift 6.3 patterns; notes backward-compatible to iOS 16 unless stated otherwise.
 
-See `references/representable-recipes.md` for complete wrapping recipes and `references/hosting-migration.md` for UIKit-to-SwiftUI migration patterns.
+See [references/representable-recipes.md](references/representable-recipes.md) for complete wrapping recipes and [references/hosting-migration.md](references/hosting-migration.md) for UIKit-to-SwiftUI migration patterns.
 
 ## Contents
 
@@ -17,7 +17,7 @@ See `references/representable-recipes.md` for complete wrapping recipes and `ref
 - [UIHostingController](#uihostingcontroller)
 - [Sizing and Layout](#sizing-and-layout)
 - [State Synchronization Patterns](#state-synchronization-patterns)
-- [Swift 6.2 Sendable Considerations](#swift-62-sendable-considerations)
+- [Sendable Considerations](#sendable-considerations)
 - [Common Mistakes](#common-mistakes)
 - [Review Checklist](#review-checklist)
 - [References](#references)
@@ -298,7 +298,7 @@ When embedding `UIHostingController` as a child, pin its view with constraints.
 
 ## State Synchronization Patterns
 
-### @Binding: Two-Way Sync (SwiftUI <-> UIKit)
+### `@Binding`: Two-Way Sync (SwiftUI <-> UIKit)
 
 Use `@Binding` when both sides read and write the same value. The coordinator writes to `parent.bindingProperty` in delegate callbacks; `updateUIView` reads the binding and pushes it into the UIKit view.
 
@@ -353,9 +353,9 @@ func updateUIView(_ uiView: UITextView, context: Context) {
 
 Without the guard, setting `uiView.text` may trigger the delegate's `textViewDidChange`, which writes to `parent.text`, which triggers `updateUIView` again.
 
-## Swift 6.2 Sendable Considerations
+## Sendable Considerations
 
-UIKit delegate protocols are not `Sendable`. When the coordinator conforms to a UIKit delegate, it inherits main-actor isolation from UIKit. Mark coordinators `@MainActor` or use `nonisolated` only for methods that truly do not touch UIKit state. In Swift 6.2 with strict concurrency:
+UIKit delegate protocols are not `Sendable`. When the coordinator conforms to a UIKit delegate, it inherits main-actor isolation from UIKit. Mark coordinators `@MainActor` or use `nonisolated` only for methods that truly do not touch UIKit state. In Swift 6 strict concurrency:
 
 ```swift
 @MainActor
@@ -415,14 +415,14 @@ If passing closures across isolation boundaries, ensure they are `@Sendable` or
 - [ ] `UIHostingController` properly added as child (`addChild` + `didMove(toParent:)`)
 - [ ] Sizing strategy chosen (`intrinsicContentSize` vs fixed `frame` vs `sizeThatFits`)
 - [ ] Environment values read in `updateUIView` via `context.environment` where needed
-- [ ] Coordinator marked `@MainActor` for Swift 6.2 strict concurrency
+- [ ] Coordinator marked `@MainActor` for strict concurrency
 - [ ] Modal controllers dismiss in all delegate exit paths (success, cancel, error)
 - [ ] `UIHostingConfiguration` used for collection/table view cells instead of manual hosting (iOS 16+)
 
 ## References
 
-- Wrapping recipes: `references/representable-recipes.md`
-- Migration patterns: `references/hosting-migration.md`
-- Apple docs: [UIViewRepresentable](https://sosumi.ai/documentation/SwiftUI/UIViewRepresentable)
-- Apple docs: [UIViewControllerRepresentable](https://sosumi.ai/documentation/SwiftUI/UIViewControllerRepresentable)
-- Apple docs: [UIHostingController](https://sosumi.ai/documentation/SwiftUI/UIHostingController)
+- Wrapping recipes: [references/representable-recipes.md](references/representable-recipes.md)
+- Migration patterns: [references/hosting-migration.md](references/hosting-migration.md)
+- Apple docs: [UIViewRepresentable](https://sosumi.ai/documentation/swiftui/UIViewRepresentable)
+- Apple docs: [UIViewControllerRepresentable](https://sosumi.ai/documentation/swiftui/UIViewControllerRepresentable)
+- Apple docs: [UIHostingController](https://sosumi.ai/documentation/swiftui/UIHostingController)

package/pipeline/skills/shared/external/swiftui-uikit-interop/references/hosting-migration.md

@@ -117,7 +117,7 @@ final class DashboardViewController: UIViewController {
 }
 ```
 
-### With @Observable Model
+### With `@Observable` Model
 
 Pass an `@Observable` model to avoid reassigning `rootView` manually. SwiftUI tracks changes automatically:
 
@@ -247,7 +247,7 @@ extension EnvironmentValues {
 
 ## 4. Data Sharing Between UIKit and SwiftUI
 
-### Using @Observable (iOS 17+)
+### Using `@Observable` (iOS 17+)
 
 The cleanest approach. Create an `@Observable` model, pass it to both UIKit and SwiftUI code:
 
@@ -373,7 +373,7 @@ func collectionView(
                 ProgressView()
             }
             .frame(width: 60, height: 60)
-            .clipShape(RoundedRectangle(cornerRadius: 8))
+            .clipShape(.rect(cornerRadius: 8))
 
             VStack(alignment: .leading) {
                 Text(item.title).font(.headline)

package/pipeline/skills/shared/external/swiftui-uikit-interop/references/representable-recipes.md

@@ -381,7 +381,7 @@ struct ImagePickerDemo: View {
                             .resizable()
                             .scaledToFill()
                             .frame(width: 100, height: 100)
-                            .clipShape(RoundedRectangle(cornerRadius: 8))
+                            .clipShape(.rect(cornerRadius: 8))
                     }
                 }
             }

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

@@ -31,7 +31,7 @@ Use the narrowest tool that matches the job.
 | OAuth or third-party sign-in | `ASWebAuthenticationSession` |
 | Back-deploy below iOS 26 or use missing legacy-only WebKit features | `WKWebView` fallback |
 
-Prefer `WebView` and `WebPage` for modern SwiftUI apps targeting iOS 26+. Apple’s WWDC25 guidance explicitly recommends migrating SwiftUI apps away from UIKit/AppKit WebKit wrappers when possible.
+Prefer `WebView` and `WebPage` for modern SwiftUI apps targeting iOS 26+. Apple's WWDC25 guidance explicitly recommends migrating SwiftUI apps away from UIKit/AppKit WebKit wrappers when possible.
 
 Do not use embedded web views for OAuth. That stays an `ASWebAuthenticationSession` flow.
 
@@ -79,7 +79,7 @@ struct ArticleDetailView: View {
 }
 ```
 
-See `references/loading-and-observation.md` for full examples.
+See [references/loading-and-observation.md](references/loading-and-observation.md) for full examples.
 
 ## Loading and Observing with WebPage
 
@@ -133,7 +133,7 @@ Task {
 }
 ```
 
-See `references/loading-and-observation.md` for stronger patterns and the load-sequence examples.
+See [references/loading-and-observation.md](references/loading-and-observation.md) for stronger patterns and the load-sequence examples.
 
 ## Navigation Policies
 
@@ -168,7 +168,7 @@ final class ArticleNavigationDecider: WebPage.NavigationDeciding {
 
 Keep app-level deep-link routing in the navigation skill. This skill owns navigation that happens inside embedded web content.
 
-See `references/navigation-and-javascript.md` for complete patterns.
+See [references/navigation-and-javascript.md](references/navigation-and-javascript.md) for complete patterns.
 
 ## JavaScript Integration
 
@@ -198,7 +198,7 @@ let result = try await page.callJavaScript(
 
 Important boundary: the native SwiftUI WebKit API clearly supports Swift-to-JavaScript calls, but it does not expose an obvious direct replacement for `WKScriptMessageHandler`. If you need coarse JS-to-native signaling, a custom navigation or callback-URL pattern can work, but document it as a workaround pattern, not a guaranteed one-to-one replacement.
 
-See `references/navigation-and-javascript.md`.
+See [references/navigation-and-javascript.md](references/navigation-and-javascript.md).
 
 ## Local Content and Custom URL Schemes
 
@@ -221,7 +221,7 @@ Use this for:
 
 Do not overuse custom schemes for normal remote content. Prefer standard HTTPS for server-hosted pages.
 
-See `references/local-content-and-custom-schemes.md`.
+See [references/local-content-and-custom-schemes.md](references/local-content-and-custom-schemes.md).
 
 ## WebView Customization
 
@@ -239,7 +239,7 @@ Apply them only when the user experience needs them.
 - Add Find in Page when the content is document-like.
 - Sync scroll position only when the app has a sidebar, table of contents, or other explicit navigation affordance.
 
-Apple’s HIG also applies here: support back/forward navigation when appropriate, but do not turn an app web view into a general-purpose browser.
+Apple's HIG also applies here: support back/forward navigation when appropriate, but do not turn an app web view into a general-purpose browser.
 
 ## Common Mistakes
 
@@ -267,7 +267,7 @@ Apple’s HIG also applies here: support back/forward navigation when appropriat
 
 ## References
 
-- Loading and observation: `references/loading-and-observation.md`
-- Navigation and JavaScript: `references/navigation-and-javascript.md`
-- Local content and custom schemes: `references/local-content-and-custom-schemes.md`
-- Migration and fallbacks: `references/migration-and-fallbacks.md`
+- Loading and observation: [references/loading-and-observation.md](references/loading-and-observation.md)
+- Navigation and JavaScript: [references/navigation-and-javascript.md](references/navigation-and-javascript.md)
+- Local content and custom schemes: [references/local-content-and-custom-schemes.md](references/local-content-and-custom-schemes.md)
+- Migration and fallbacks: [references/migration-and-fallbacks.md](references/migration-and-fallbacks.md)