Refresh Swift

---
name: refresh-swift
description: Research current Swift/SwiftUI/platform best practices from gold-standard sources and update the docs/setup/swift/ reference files and the modern-swiftui.md guardrails stub. Also refreshes the App Store submission facts embedded in the appstore-preflight skill. Use when the user says "refresh swift", "update swift guidance", "refresh swift best practices", or "refresh swiftui".
---

# Refresh Swift Best Practices Skill

**Goal:** Research the current state of Swift language, SwiftUI, concurrency, testing, and platform-specific patterns from primary sources and update the sectioned reference docs in `docs/setup/swift/` plus the `modern-swiftui.md` guardrails stub in the skills repo. These files are baked into every new Apple platform project — keeping them current is critical for guiding correct architectural choices. The same run also refreshes the App Store submission facts embedded in the `appstore-preflight` skill (Step 4) — those shift on the same iOS/Xcode cadence.

**Scope:** iOS 18 through the current stable release only. **Hard exclude** any pre-release, beta, or unannounced OS API. When in doubt, omit.

**Version-axis rules (prevents drift):**
1. **Verify version names before writing any header.** Search for the current stable iOS/macOS/Swift/Xcode versions first — never infer the next version by incrementing (Apple jumped iOS 18 → iOS 26; a past run invented a phantom "iOS 19" from that assumption). Every fact written must cite a real, shipped version string.
2. **Concurrency and testing guidance is keyed to the Swift language version** (e.g. Swift 6.2), not the iOS version — label and research those files on that axis.
3. For every file, the research question is **"what changed since this file's `Updated:` date?"** against the current stable release — not a fixed "iOS 18+?" checklist frozen at authoring time.

---

## Step 1 — Locate Files

Find the files to update:

```bash
# Project's working copies (these are what get updated in use)
ls docs/setup/swift/

# Skills repo stub originals (also update these so new projects get current content)
find . -path "*/setup/stubs/swift/*.md" | sort
find . -path "*/setup/stubs/modern-swiftui.md"
```

Read every file completely before proceeding — treat the current content as the baseline.

If `docs/setup/swift/` does not exist, ask whether the user wants to run `/setup` first or update just the stubs in the skills repo.

---

## Step 2 — Research Current Best Practices

Use WebSearch and WebFetch to pull current content from the gold-standard sources below. For each finding, note the iOS/Swift version where the pattern was introduced or changed.

### Gold-Standard Sources

- **Hacking with Swift** — hackingwithswift.com (Paul Hudson)
- **Swift with Majid** — swiftwithmajid.com (Majid Jabrayilov)
- **SwiftLee** — swiftlee.com (Antoine van der Lee)
- **Apple Human Interface Guidelines** — developer.apple.com/design/human-interface-guidelines (check the per-page change log; new device form factors land here first)
- **Apple Developer Documentation** — developer.apple.com/documentation
- **Apple WWDC sample apps** — developer.apple.com/documentation/SampleCode
- **Apple Swift updates** — developer.apple.com/documentation/updates/swift
- **Point-Free** — pointfree.co (modern state management)

### Curated Agent-Skill Repos (diff sources — highest signal per token)

These community skills are already distilled into agent-facing rules, so diffing them against our stubs is far cheaper than crawling articles. Clone shallow (`git clone --depth 1`) into a temp dir, compare, **port ideas in our lean ✅/❌ style — never copy files** (same rule as the BMAD upstream sync). Pinned to trusted authors only; the wider `twostraws/swift-agent-skills` directory is an *index* to check for new entries by these authors, not a blanket source (its own README warns listing ≠ endorsement).

- **github.com/twostraws/SwiftUI-Agent-Skill**, **SwiftData-Agent-Skill**, **Swift-Concurrency-Agent-Skill**, **Swift-Testing-Agent-Skill**, **SwiftAgents** (Paul Hudson)
- **github.com/Dimillian/Skills** (Thomas Ricouard — concurrency, SwiftUI performance, Liquid Glass)
- **github.com/AvdLee/Swift-Concurrency-Agent-Skill**, **Swift-Testing-Agent-Skill** (Antoine van der Lee)

**House-style filter when porting:** leanwheel deliberately bans per-view ViewModels (views are the ViewModel — logic as computed properties in the View, mutations in testable services). Some of these sources recommend ViewModel extraction for testability — **do not port that**; map any such advice onto our service-extraction pattern (anti-patterns.md #1/#11) instead.

### Research by Target File

Research each section in turn. For each: compare findings against the existing file content, note what is still accurate, what is outdated, and what is missing.

**`state-management.md`**
- `@Observable` macro — any changes in iOS 18+?
- `@State`, `@Binding`, `@Bindable`, `@Environment` — any new wrappers or deprecations?
- Unidirectional data flow patterns

**`concurrency.md`**
- Swift 6 strict concurrency — what changed for SwiftUI apps?
- `.task` / `.task(id:)` — any new overloads or behaviors?
- `@MainActor`, `actor` — any new guidance?
- `TaskGroup` patterns

**`architecture.md`**
- Feature-based project structure — any WWDC sample app changes?
- Service injection via `@Environment` — any new patterns?
- `NavigationStack` — any new value-based navigation APIs?

**`ui-composition.md`**
- New SwiftUI layout containers introduced in iOS 18+?
- `List` vs `ScrollView` — any new lazy layout options?
- View modifier changes

**`testing.md`**
- Swift Testing framework updates (new annotations, `@Suite` changes)?
- Any new Xcode test runner integration?
- Core Data test patterns

**`testability.md`**
- `PreviewModifier` / preview-seeding APIs — any changes since iOS 18?
- SwiftData `ModelConfiguration` / in-memory container patterns — any new options?
- XCUITest — new launch/automation APIs, or replacements (e.g. Xcode UI-automation changes)?
- Launch-argument / `ProcessInfo` patterns still the recommended seed trigger?
- Accessibility-identifier best practices — any new locator guidance?

**`swiftdata.md`**
- `#Predicate` — newly supported (or still-crashing) constructs?
- Migration APIs (`VersionedSchema`, `SchemaMigrationPlan`) — any changes?
- CloudKit-backed store constraints — any relaxed or added?
- New model macros, index types, or fetch options since the file's Updated date?

**`accessibility.md`**
- New accessibility modifiers or environment values?
- Dynamic Type / scaled-font APIs — any changes?
- Any new Voice Control / VoiceOver / Assistive Access requirements affecting code?

**`anti-patterns.md`**
- New patterns AI tools commonly generate that should be added to the rejection list?
- Any anti-patterns that are now acceptable (rare — document the reason)?
- Newly deprecated/superseded APIs for the #13 modernization table?

**`iphone-duo.md`** (if present in `docs/setup/swift/` or stubs)
- `ArrangementView` / `UIArrangementViewController` — still beta, or shipped? Any new styles or sizing modifiers?
- `ReservedRegion` — any new `Kind` values or query options beyond `occlusion` / `division`?
- Toolbar vertical-axis APIs (`axisBehavior`, `visibilityPriority`, `toolbarVerticalBehavior`, `toolbarVerticalEdge`) — renamed or extended?
- Minimum SDK for the full-screen experience — still Xcode 27.1 / iOS 27.1?
- Any new pose, display, or camera APIs since the file's Updated date?

**`ipados-specific.md`** (if present in `docs/setup/swift/` or stubs)
- `NavigationSplitView` — any new column options or behaviors in iPadOS 18+?
- Multi-window and scene APIs — any new `openWindow` or `WindowGroup` options?
- Drag-and-drop — any new `Transferable` representations or drop modifiers?
- Pointer/hover — any new `hoverEffect` styles?
- Stage Manager implications — any new multi-window guidance from WWDC?

**`macos-specific.md`** (if present in `docs/setup/swift/` or stubs)
- `MenuBarExtra` — any new style or content options?
- `Table` — any new column types, row actions, or sorting APIs?
- `Settings` scene — any new navigation or tab patterns?
- Window management — any new `openWindow`, `WindowGroup`, or `defaultSize` options?
- File operations — any changes to `fileImporter`/`fileExporter` modifiers?
- macOS 15+ (Sequoia) — any new scene types or system integration APIs?

---

## Step 3 — Write Updated Files

### Field knowledge is protected — read this before editing anything

Two kinds of claim live in these files and they age differently. **Research knowledge** comes
from Apple docs, WWDC, release notes, and curated authors, and goes stale on the OS/Xcode
cadence — that is what this skill exists to refresh. **Field knowledge** comes from trial and
error on a real shipping project: a mechanism observed, a symptom paid for, a fix verified by
running. It is typically *absent* from any primary source, which is precisely why it is
valuable, and it does **not** go stale on a version bump.

Field-earned rules are marked with an HTML comment after their heading:

```bash
grep -rn "<!-- FIELD" docs/setup/swift/ "{skills_path}/.claude/skills/setup/stubs/swift/"
```

**Run that grep before writing, and treat every hit as protected.** A refresh pass may:

- ✅ **Append** a dated verification note beside it (`<!-- verified still current YYYY-MM-DD -->`).
- ✅ **Version-scope** it when a cited source establishes the range ("on iOS 26" → "on iOS 26–26.x").
- ✅ **Retire** it — move it to a `## Retired` section with the citation that shows the
  **mechanism** no longer exists, and name it in the report.
- ❌ **Never silently rewrite or delete it** because newer general guidance covers the same topic.

The bar for retirement is the mechanism, not the topic. *"Apple's current docs recommend X"* does
not retire a rule about what happens when X is used near a translucent bar. *"The bar is no longer
translucent as of iOS 28, per <release note>"* does. When a research finding appears to conflict
with a field rule and cannot meet that bar, **surface the conflict in the report and change
nothing** — the person who paid for the rule decides whether it retires.

Full convention, including how to add a new field rule: `docs/setup/swift/PROVENANCE.md`.

Note that some files are field-derived end to end and carry the marker once under their H1 —
`demo-data-and-copy.md`, and large parts of `simulator.md`, `testability.md`, `xcode-footguns.md`,
`core-data-cloudkit.md`, and `localization.md`. Research findings **augment** these; they do not
replace them.

For each file with changes:

1. Update `docs/setup/swift/{file}.md` with current content.
2. Update the corresponding stub at `{skills_path}/.claude/skills/setup/stubs/swift/{file}.md` so new projects get the same content.
3. Add or update a `> **Updated:** {today's date} — iOS/iPadOS/macOS {N}+` line at the top of each changed file, using the correct platform label for that file.

### Formatting Rules (preserve these exactly)

- `#` title, then `> iOS {N}+ | one-line scope note`
- `##` section headers
- Fenced code blocks with `// ✅` correct and `// ❌` rejected patterns side-by-side
- Tables for comparison content (property wrappers, List vs ScrollView decisions)
- No conversational filler — declarative, RFC-style tone

### Guardrails Block (`modern-swiftui.md`)

After updating the sectioned files, review the guardrails stub (`modern-swiftui.md`). It is a
**managed block** — a pointer to `docs/setup/swift/` plus the tripwires that must be known before
a plan is formed. Update it only if:
- A row was added to, or removed from, the "hard rejection" table (document why on removal)
- A checklist item changed
- A **new reference file** was added to `stubs/swift/` — add it to the pointer list at the top
- A tripwire's one-line statement no longer matches the file it links to

Rules for editing it:
- **Never inline a reference file's contents.** The block is loaded every turn, and an inlined
  copy drifts from its source. One line plus a `→ file.md` pointer, always.
- **Never delete a tripwire** whose linked section is `<!-- FIELD -->`-marked without meeting the
  retirement bar above.
- **Bump the `vN` in the `<!-- leanwheel:guardrails swift vN -->` markers** whenever the block's
  content changes. `/upgrade-project` uses that version to detect and re-sync stale copies in
  existing projects; leaving it unchanged means no project ever receives the update.

The guardrails file must stay under ~90 lines — it lives in CLAUDE.md and is loaded every turn.

---

## Step 4 — Refresh App Store Submission Facts (`appstore-preflight`)

App Store submission requirements move on the same annual iOS/Xcode cadence as the coding guidance (plus litigation-driven changes mid-cycle), so this run also refreshes the requirement facts in `{skills_path}/.claude/skills/appstore-preflight/` — `SKILL.md`, the branch files `checks-cloudkit.md` / `checks-storekit.md`, and `submission-checklist.template.md`. Skip this step only if that skill file is not reachable (skills repo absent).

**Cheap gate first:** read the skill's "Currency note" date, then check developer.apple.com/news/upcoming-requirements/ and Apple's App Review Guidelines changelog for anything newer. If nothing has changed since that date, update nothing and report "appstore-preflight facts confirmed current" — done.

Otherwise research what moved:

- **developer.apple.com/news/upcoming-requirements/** — the annual minimum Xcode/SDK upload floor, enforcement deadlines
- **App Review Guidelines** (developer.apple.com/app-store/review/guidelines/) + developer.apple.com/news/ — guideline text changes (privacy 5.1.x, business 3.1.x, design 4.x)
- **developer.apple.com/support/third-party-SDK-requirements/** — listed-SDK additions/removals
- **Privacy plumbing** — new `NS*UsageDescription` keys, new required-reason API categories or reason codes, privacy-manifest enforcement changes (new ITMS codes)
- **⚠️VOLATILE items specifically** — external purchase link rules (US storefront litigation), `UIRequiresFullScreen`/iPad windowing enforcement, launch-screen mandates, age-rating system, EU DSA / regulatory, TestFlight policy changes

Then update in `appstore-preflight/` (each fact lives in exactly one of those files — grep for it):

1. The "Currency note" date, and any ⚠️VOLATILE flags now resolved (or newly needed)
2. The fact tables — purpose-string keys, required-reason categories/codes, listed SDKs, config/asset rules and their ITMS codes
3. Checklist items for any new App Store Connect requirements — in `submission-checklist.template.md`. Keep its `{omit if no StoreKit}` / `{omit if no CloudKit}` / `{+ … if universal}` markers intact; a new conditional kind needs `render-checklist.sh` and `scripts/test/checklist-render.sh` updated too, or the render fails on purpose.

**Facts only** — never restructure that skill's steps, severity scheme, or output formats. This updates the skills-repo file only; `appstore-preflight` has no per-project guidance copies.

Same gate, same run: refresh the store facts embedded in `{skills_path}/.claude/skills/appstore-connect/` — the required screenshot classes and accepted pixel sizes (`op-assets.md` store facts, `compose.swift` output-size table, `asc-lint.sh` accepted-size table, `sim.sh` `verify_store_capture`) and the metadata character limits (`op-metadata.md` rules, `asc-lint.sh` limits); bump the SKILL.md Currency note date. Sources: developer.apple.com/help/app-store-connect/reference/screenshot-specifications/ and the App Store Connect help "app information" field limits. Facts only.

---

## Step 5 — Report to User

Summarize:

1. **What changed:** Bullet list per file — new patterns added, outdated patterns removed, iOS/Swift version bumps.
2. **What stayed the same:** Brief confirmation that still-valid content was preserved.
3. **App Store facts:** What changed in `appstore-preflight` (or "confirmed current").
4. **Sources consulted:** Which gold-standard sources had relevant current content.
5. **Reminder:** Existing projects that already have the sectioned files in `docs/setup/swift/` will have their copies updated by this run. Projects that haven't run `/setup` yet will get the updated stubs when they do.

---

## Step 6 — Offer Audit Handoff

After reporting, ask:

> "Guidance updated. Run `/swift-audit` now to check the current codebase against the new patterns? (y/n)"

If yes: invoke `/swift-audit` immediately. If no: stop.