swiftui-performance-audit

Files (23)

• SKILL.md
• code-smells.md · references/
• demystify-swiftui-performance-wwdc23.md · references/
• optimizing-swiftui-performance-instruments.md · references/
• profiling-intake.md · references/
• report-template.md · references/
• trace-analysis.md · references/
• trace-recording.md · references/
• understanding-hangs-in-your-app.md · references/
• understanding-improving-swiftui-performance.md · references/
• analyze_trace.py · scripts/
• __init__.py · scripts/instruments_parser/
• causes.py · scripts/instruments_parser/
• correlate.py · scripts/instruments_parser/
• events.py · scripts/instruments_parser/
• hangs.py · scripts/instruments_parser/
• hitches.py · scripts/instruments_parser/
• summary.py · scripts/instruments_parser/
• swiftui.py · scripts/instruments_parser/
• time_profiler.py · scripts/instruments_parser/
• xctrace.py · scripts/instruments_parser/
• xml_utils.py · scripts/instruments_parser/
• record_trace.py · scripts/

SKILL.md (first lines)

# SwiftUI Performance Audit

## Overview

Audit SwiftUI view performance end-to-end, from instrumentation and baselining to root-cause analysis and concrete remediation steps.

## 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.

Ask the user to classify the symptom if possible — this steers the review and any later profiling request:
- CPU spike or battery drain
- Janky scrolling or dropped frames
- High memory or image pressure
- Hangs or unresponsive interactions
- Excessive or unexpectedly broad view updates

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).

Use `references/code-smells.md` for the detailed smell catalog, Observation-specific fan-out guidance (iOS 17+ `@Observable` vs iOS 16- `ObservableObject`), the triage order, and remediation patterns.

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 (Release build).
- 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.

Use `references/profiling-intake.md` for the full intake checklist, default profiling request, artifacts to collect, and common traps (Debug-build timing distortion, Simulator blind spots).

### Automated trace capture and analysis

Instead of (or alongside) asking the user for screenshots, drive Instruments directly with the bundled scripts:

- `scripts/record_trace.py` wraps `xctrace record` — SwiftUI template by default, manual stop via Ctrl+C / stop-file / `--time-limit`, JSON device+template discovery, agent-orchestratable exit codes. See `references/trace-recording.md` for the attach/launch/background/time-boxed flows and the **SwiftUI-template-needs-a-real-device-or-the-host-Mac** rule (Simulator → fall back to `Time Profiler`).
- `scripts/analyze_trace.py` parses a `.trace` bundle into a structured report (SwiftUI updates, Time Profiler, hangs, animation hitches) and correlates lanes. See `references/trace-analysis.md` for `--list-logs` / `--list-signposts` / `--window` scoping and `--json-only` output.

For a macOS app like the ones this project targets, the host Mac supports the SwiftUI template, so both scripts work against a locally-run Release build. The scripts are stdlib-only Python 3 (no pip dependencies) and shell out to `xctrace`.

## 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. Distinguish code-level suspicion from trace-backed evidence, and call out when profiling is still insufficient and what additional evidence would reduce uncertainty.

## 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` into derived state updated from inputs, model-layer precomputation, memoized helpers, or background preprocessing. Use `@State` only for view-owned state, not as an ad hoc cache for arbitrary computation.
- Use `equatable()` only when equality is cheaper than recomputing the subtree and the inputs are truly value-semantic — not as a blanket fix.
- Downsample images before rendering.
- Reduce layout complexity or use fixed sizing where possible.

## Common Code Smells (and Fixes)

See `references/code-smells.md` for the full catalog — expensive formatters and heavy computed work in `body`, sorting/filtering during render, unstable identity, top-level conditional view swapping, main-thread image decode, and Observation fan-out (split by iOS 17+ `@Observable` vs iOS 16- `ObservableObject`) — plus the `@State`-is-not-a-cache and conditional-`equatable()` remediation notes and the impact-ordered triage list.

## 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.

## Outputs

Provide:
- A short metrics table (before/after if available).
- Top issues (ordered by impact).
- Proposed fixes with estimated effort.

Use `references/report-template.md` when formatting the final audit.

## References

- Common code smells and remediation patterns: `references/code-smells.md`
- Profiling intake and collection checklist: `references/profiling-intake.md`
- Audit output template: `references/report-template.md`
- Recording a trace with `scripts/record_trace.py`: `references/trace-recording.md`
- Analyzing a `.trace` bundle with `scripts/analyze_trace.py`: `references/trace-analysis.md`

Add Apple documentation and WWDC resources under `references/` as they are supplied by the user.
- Optimizing SwiftUI performance with Instruments: `references/optimizing-swiftui-performance-instruments.md`
- Understanding and improving SwiftUI performance: `references/understanding-improving-swiftui-performance.md`
- Understanding hangs in your app: `references/understanding-hangs-in-your-app.md`
- Demystify SwiftUI performance (WWDC23): `references/demystify-swiftui-performance-wwdc23.md`

From ducko-im/ducko, GPL-3.0.

More from ducko-im/ducko