Approach: Production-First Iterative Refactoring — This skill is built for production enterprise codebases where stability and reviewability matter more than speed. Architecture changes are delivered through iterative refactoring — small, focused PRs (≤200 lines, single concern) tracked in a refactoring/ directory. Critical safety issues ship first; cosmetic improvements come last.

SwiftUI MVVM Architecture (iOS 17+)

Enterprise-grade SwiftUI MVVM architecture skill. Opinionated: prescribes @Observable ViewModels, Router navigation, constructor injection, ViewState enum, and Repository-based networking. Adopts a production-first iterative refactoring approach — every pattern is chosen for testability, reviewability, and safe incremental adoption in large teams. For non-architectural SwiftUI API guidance (animations, modern API replacements, Liquid Glass), use a general SwiftUI skill instead.

Architecture Layers

View Layer         → SwiftUI Views. Declarative UI only. Owns ViewModel via @State.
ViewModel Layer    → @Observable @MainActor final class. Exposes ViewState<T>.
Repository Layer   → Protocol-based data access. Hides data source details.
Service Layer      → URLSession, persistence. Injected via protocol.

Quick Decision Trees

"Should this View have a ViewModel?"

Is there business logic, networking, or complex state?
├── YES → Create @Observable ViewModel
└── NO → Is it a reusable UI component (button, card, cell)?
    ├── YES → Plain struct with data parameters, NO ViewModel
    └── NO → No ViewModel needed unless it simplifies testing

"How should I own this ViewModel?"

Does THIS view create the ViewModel?
├── YES → @State private var viewModel = MyViewModel()
└── NO → Does the view need $ bindings to ViewModel properties?
    ├── YES → @Bindable var viewModel: MyViewModel
    └── NO → let viewModel: MyViewModel (plain property)

"Where do dependencies come from?"

ViewModel always receives dependencies via constructor:
  init(repository: ItemRepositoryProtocol)

How does the View get the dependency to pass?
├── Shared service (used across many screens)
│   └── Register via @Entry in EnvironmentValues
│       View reads @Environment(\.repo), passes to VM init
├── Screen-specific dependency (passed by parent)
│   └── View receives it as init parameter, passes to VM init
└── Outside view hierarchy (background service, deep utility)
    └── @Injected property wrapper (legacy/convenience only)

Workflows

Default workflow: Analyze & Refactor (below). New screen creation applies the same patterns but from a clean slate. In production enterprise codebases, most work is iterative modernization — not greenfield.

Workflow: Analyze & Refactor Existing Codebase

When: First encounter with a legacy SwiftUI codebase — the most common enterprise scenario.

1. Scan for anti-patterns using the detection checklist (references/anti-patterns.md)
2. Create refactoring/ directory with per-feature plan files (references/refactoring-workflow.md)
3. Write each issue with full description (Location, Severity, Problem, Fix) — titles alone get forgotten
4. Categorize issues by severity: 🔴 Critical → 🟡 High → 🟢 Medium
5. Plan Phase 1 PR: fix critical safety issues only (≤200 lines per PR)
6. Execute one PR at a time. New findings go to refactoring/discovered.md with full descriptions, NOT into current PR
7. After completing each fix: mark the task - [x] in the feature file and update refactoring/README.md progress table
8. Proceed through phases: Critical → @Observable migration → ViewState → Architecture

Workflow: Create a New Screen

When: Building a new feature screen from scratch. Apply enterprise patterns from the start so no refactoring is needed later.

1. Define the data model and repository protocol (references/networking.md)
2. Create ViewModel: @Observable @MainActor final class with ViewState<T> (references/mvvm-observable.md)
3. Add // MARK: - sections: Properties, Init, Actions, Computed Properties
4. Create the screen View with @State private var viewModel
5. Wire data loading via .task { await viewModel.load() }
6. Add navigation route to Router enum (references/navigation.md)
7. Register dependencies in @Environment or @Injected (references/dependency-injection.md)
8. Create test file with mock repository (references/testing.md)

Workflow: Migrate ViewModel from ObservableObject

When: Modernizing existing code from Combine-based observation to @Observable.

1. Add Self._printChanges() to the View body — note current redraw triggers
2. Replace ObservableObject conformance with @Observable macro
3. Remove all @Published — plain var properties are auto-tracked
4. Replace @StateObject with @State in the owning View
5. Replace @ObservedObject with plain let (or @Bindable if $ bindings needed)
6. Replace @EnvironmentObject with @Environment(Type.self)
7. Add @MainActor to the ViewModel class declaration
8. Verify with Self._printChanges() — confirm fewer/more specific redraw triggers
9. Run existing tests — all must pass
10. Remove Self._printChanges() before committing

Code Generation Rules

<critical_rules> Whether generating new code or refactoring existing code, every output must be production-ready and PR-shippable — small, focused, and testable. ALWAYS:

1. Mark ViewModels as @Observable @MainActor final class
2. Use private(set) var for state properties modified only by the ViewModel
3. Use ViewState<T> enum for async data — never separate boolean flags
4. Inject dependencies via constructor with protocol types
5. Use .task { } for initial data loading
6. Keep View bodies pure — no Task { } inside body, no business logic
7. Use typed enum Route: Hashable for navigation
8. Add // MARK: - sections: Properties, Init, Actions, Computed Properties
9. Import only Foundation (and domain modules) in ViewModels — never SwiftUI
10. Keep every generated file ≤ 400 lines. Extract subviews into dedicated files. Split ViewModel logic into extensions (MyVM+Search.swift) or child ViewModels when approaching that limit. For legacy files, log a split task in the feature's refactoring/ plan instead of forcing it mid-refactor.
11. Before modifying a View or ViewModel, output a brief <thought> analyzing its current state and redraw triggers.
12. @Observable instances passed to .environment(...) must be owned by a stable @State — .environment(AppTheme()) creates a new AppTheme on every parent redraw, which defeats the point of environment injection and breaks observation. Always own it: @State private var theme = AppTheme() then .environment(theme).
13. ViewModel signals navigation intent via closures; View owns the @State toggle. Instead of viewModel.router.push(.profile(user)), the ViewModel exposes var onOpenProfile: ((User) -> Void)? and the View sets .onOpenProfile = { user in path.append(.profile(user)) } at wire-up time. This keeps the ViewModel ignorant of navigation mechanics (testable, reusable across hosts) while the View remains the single owner of @State path.
14. Self._printChanges() verification steps for splitting views. When fixing redraw storms, verification is a sequence, not a single check: (1) add let _ = Self._printChanges() to both the parent view body AND the split child, (2) type/tap to produce change events, (3) confirm ONLY the target child prints during the interaction — if the parent also prints, it has a hidden read of the changing value (search the body for every store.property access and verify equality-only reads use stored, not computed, state), (4) remove both _printChanges before committing. </critical_rules>

Anti-Pattern Severity Reference

When auditing a SwiftUI codebase, assign severities from this canonical table. Models systematically mis-classify these — memorize the boundaries.

Decision rules:

• Critical = crash, data corruption, or blocks all testing
• High = not a crash, but breaks an architectural invariant that cascades (unmanaged tasks, lost state, hidden coupling)
• Medium = functional code with a long-tail maintenance cost or impossible states

Migration Mapping: ObservableObject → @Observable

This table must appear verbatim in every "migrate from ObservableObject" response — readers copy it into code reviews.

Common gotcha: models often apply @State to the VM in the owning view but forget to switch @ObservedObject → let or @Bindable in child views — the whole chain must migrate together or child views won't observe changes.

When generating tests, ALWAYS:

1. Use protocol mocks with var stubbed* and var *CallCount tracking
2. Test through public interface, never test private methods
3. Mark test classes/structs @MainActor when testing @MainActor ViewModels
4. Use await fulfillment(of:) for async tests — NEVER wait(for:) (deadlocks)
5. Include memory leak detection with addTeardownBlock { [weak sut] in XCTAssertNil(sut) }

Fallback Strategies & Loop Breakers

<fallback_strategies> When refactoring legacy code, you may encounter stubborn Swift compiler errors. If you fail to fix the same error twice, break the loop:

1. @State vs @Bindable Generics: If the compiler complains about property wrapper bindings ($), ensure you use @Bindable in subviews for @Observable types. Why: @State creates ownership (single source of truth), while @Bindable enables two-way bindings without ownership — the compiler enforces this distinction. If unresolved, temporarily use plain let and closure callbacks to unblock compilation.
2. NavigationStack Path Issues: If the compiler complains about Hashable routes or navigationDestination types, ensure your enum Route is perfectly Hashable and avoid passing complex models (prefer passing IDs). Why: NavigationStack serializes the path for state restoration, so every route case must be deterministically hashable.
3. Revert and Restart: If a View refactor spirals into 50+ compiler errors related to ambiguous type inference, stop. Propose reverting the changes and breaking the problem into two smaller phases (e.g. migrate properties first, then extract subviews). Why: SwiftUI's type inference cascades — a single change can destabilize unrelated code, and small PRs are far easier to review and debug. </fallback_strategies>

Confidence Checks

Before finalizing generated or refactored code, verify ALL:

□ No duplicate functionality — searched codebase for existing implementations
□ Architecture adherence — follows patterns already established in the project
□ Naming conventions — matches existing project naming style
□ Import check — ViewModel imports only Foundation, NOT SwiftUI
□ @MainActor — present on all ViewModel class declarations
□ ViewState — used for all async data, no separate isLoading/error booleans
□ DI — dependencies injected via protocol, not accessed via singletons
□ Task management — .task modifier for lifecycle, explicit cancellation handling
□ CancellationError — handled silently, never shown to user
□ Tests — corresponding test file exists or is created alongside
□ PR scope — changes within defined scope, new findings go to `refactoring/discovered.md`
□ File size — new files ≤ 400 lines; existing oversized files have a split task logged in `refactoring/`

Companion Skills

Before generating async ViewModel, Task, or actor code: determine the project's concurrency approach. If unclear from context, ask the user.

If unclear, ask: "Does this project use Swift Concurrency (async/await) or GCD for async operations?"

References