Update to Build iOS Apps

{
  "name": "swiftui-view-refactor",
  "description": "Refactor SwiftUI view files into stable, testable structure. Use when splitting large views, tightening data flow, or cleaning Observation ownership.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 226
    },
    {
      "relative_path": "references/mv-patterns.md",
      "size_in_bytes": 5568
    }
  ],
  "skill_md_contents": "---\nname: swiftui-view-refactor\ndescription: Refactor SwiftUI view files into stable, testable structure. Use when splitting large views, tightening data flow, or cleaning Observation ownership.\n---\n\n# SwiftUI View Refactor\n\n## Overview\nRefactor SwiftUI views toward small, explicit, stable view types. Default to vanilla SwiftUI: local state in the view, shared dependencies in the environment, business logic in services/models, and view models only when the request or existing code clearly requires one.\n\n## Core Guidelines\n\n### 1) View ordering (top → bottom)\n- Enforce this ordering unless the existing file has a stronger local convention you must preserve.\n- Environment\n- `private`/`public` `let`\n- `@State` / other stored properties\n- computed `var` (non-view)\n- `init`\n- `body`\n- computed view builders / other view helpers\n- helper / async functions\n\n### 2) Default to MV, not MVVM\n- Views should be lightweight state expressions and orchestration points, not containers for business logic.\n- Favor `@State`, `@Environment`, `@Query`, `.task`, `.task(id:)`, and `onChange` before reaching for a view model.\n- Inject services and shared models via `@Environment`; keep domain logic in services/models, not in the view body.\n- Do not introduce a view model just to mirror local view state or wrap environment dependencies.\n- If a screen is getting large, split the UI into subviews before inventing a new view model layer.\n\n### 3) Strongly prefer dedicated subview types over computed `some View` helpers\n- Flag `body` properties that are longer than roughly one screen or contain multiple logical sections.\n- Prefer extracting dedicated `View` types for non-trivial sections, especially when they have state, async work, branching, or deserve their own preview.\n- Keep computed `some View` helpers rare and small. Do not build an entire screen out of `private var header: some View`-style fragments.\n- Pass small, explicit inputs (data, bindings, callbacks) into extracted subviews instead of handing down the entire parent state.\n- If an extracted subview becomes reusable or independently meaningful, move it to its own file.\n\nPrefer:\n\n```swift\nvar body: some View {\n    List {\n        HeaderSection(title: title, subtitle: subtitle)\n        FilterSection(\n            filterOptions: filterOptions,\n            selectedFilter: $selectedFilter\n        )\n        ResultsSection(items: filteredItems)\n        FooterSection()\n    }\n}\n\nprivate struct HeaderSection: View {\n    let title: String\n    let subtitle: String\n\n    var body: some View {\n        VStack(alignment: .leading, spacing: 6) {\n            Text(title).font(.title2)\n            Text(subtitle).font(.subheadline)\n        }\n    }\n}\n\nprivate struct FilterSection: View {\n    let filterOptions: [FilterOption]\n    @Binding var selectedFilter: FilterOption\n\n    var body: some View {\n        ScrollView(.horizontal, showsIndicators: false) {\n            HStack {\n                ForEach(filterOptions, id: \\.self) { option in\n                    FilterChip(option: option, isSelected: option == selectedFilter)\n                        .onTapGesture { selectedFilter = option }\n                }\n            }\n        }\n    }\n}\n```\n\nAvoid:\n\n```swift\nvar body: some View {\n    List {\n        header\n        filters\n        results\n        footer\n    }\n}\n\nprivate var header: some View {\n    VStack(alignment: .leading, spacing: 6) {\n        Text(title).font(.title2)\n        Text(subtitle).font(.subheadline)\n    }\n}\n```\n\n### 3b) Extract actions and side effects out of `body`\n- Do not keep non-trivial button actions inline in the view body.\n- Do not bury business logic inside `.task`, `.onAppear`, `.onChange`, or `.refreshable`.\n- Prefer calling small private methods from the view, and move real business logic into services/models.\n- The body should read like UI, not like a view controller.\n\n```swift\nButton(\"Save\", action: save)\n    .disabled(isSaving)\n\n.task(id: searchText) {\n    await reload(for: searchText)\n}\n\nprivate func save() {\n    Task { await saveAsync() }\n}\n\nprivate func reload(for searchText: String) async {\n    guard !searchText.isEmpty else {\n        results = []\n        return\n    }\n    await searchService.search(searchText)\n}\n```\n\n### 4) Keep a stable view tree (avoid top-level conditional view swapping)\n- Avoid `body` or computed views that return completely different root branches via `if/else`.\n- Prefer a single stable base view with conditions inside sections/modifiers (`overlay`, `opacity`, `disabled`, `toolbar`, etc.).\n- Root-level branch swapping causes identity churn, broader invalidation, and extra recomputation.\n\nPrefer:\n\n```swift\nvar body: some View {\n    List {\n        documentsListContent\n    }\n    .toolbar {\n        if canEdit {\n            editToolbar\n        }\n    }\n}\n```\n\nAvoid:\n\n```swift\nvar documentsListView: some View {\n    if canEdit {\n        editableDocumentsList\n    } else {\n        readOnlyDocumentsList\n    }\n}\n```\n\n### 5) View model handling (only if already present or explicitly requested)\n- Treat view models as a legacy or explicit-need pattern, not the default.\n- Do not introduce a view model unless the request or existing code clearly calls for one.\n- If a view model exists, make it non-optional when possible.\n- Pass dependencies to the view via `init`, then create the view model in the view's `init`.\n- Avoid `bootstrapIfNeeded` patterns and other delayed setup workarounds.\n\nExample (Observation-based):\n\n```swift\n@State private var viewModel: SomeViewModel\n\ninit(dependency: Dependency) {\n    _viewModel = State(initialValue: SomeViewModel(dependency: dependency))\n}\n```\n\n### 6) Observation usage\n- For `@Observable` reference types on iOS 17+, store them as `@State` in the owning view.\n- Pass observables down explicitly; avoid optional state unless the UI genuinely needs it.\n- If the deployment target includes iOS 16 or earlier, use `@StateObject` at the owner and `@ObservedObject` when injecting legacy observable models.\n\n## Workflow\n\n1. Reorder the view to match the ordering rules.\n2. Remove inline actions and side effects from `body`; move business logic into services/models and keep only thin orchestration in the view.\n3. Shorten long bodies by extracting dedicated subview types; avoid rebuilding the screen out of many computed `some View` helpers.\n4. Ensure stable view structure: avoid top-level `if`-based branch swapping; move conditions to localized sections/modifiers.\n5. If a view model exists or is explicitly required, replace optional view models with a non-optional `@State` view model initialized in `init`.\n6. Confirm Observation usage: `@State` for root `@Observable` models on iOS 17+, legacy wrappers only when the deployment target requires them.\n7. Keep behavior intact: do not change layout or business logic unless requested.\n\n## Notes\n\n- Prefer small, explicit view types over large conditional blocks and large computed `some View` properties.\n- Keep computed view builders below `body` and non-view computed vars above `init`.\n- A good SwiftUI refactor should make the view read top-to-bottom as data flow plus layout, not as mixed layout and imperative logic.\n- For MV-first guidance and rationale, see `references/mv-patterns.md`.\n- In addition to the references above, use web search to consult current Apple Developer documentation when SwiftUI APIs, Observation behavior, or platform guidance may have changed.\n\n## Large-view handling\n\nWhen a SwiftUI view file exceeds ~300 lines, split it aggressively. Extract meaningful sections into dedicated `View` types instead of hiding complexity in many computed properties. Use `private` extensions with `// MARK: -` comments for actions and helpers, but do not treat extensions as a substitute for breaking a giant screen into smaller view types. If an extracted subview is reused or independently meaningful, move it into its own file.\n"
}