Swift Refactor

Swift/SwiftUI Refactor (Modular MVVM-C)

Comprehensive refactoring guide for migrating Swift/SwiftUI code to modular MVVM-C with local SPM package boundaries and App-target composition root wiring.

Mandated Architecture Stack

┌───────────────────────────────────────────────────────────────┐
│ App target: DependencyContainer, Coordinators, Route Shells   │
├───────────────────────────────────────────────────────────────┤
│ Feature modules: View + ViewModel (Domain + DesignSystem deps)│
├───────────────────────────────────────────────────────────────┤
│ Data package: repositories, remote/local stores, sync, retry  │
├───────────────────────────────────────────────────────────────┤
│ Domain package: models, repository/coordinator/error protocols │
└───────────────────────────────────────────────────────────────┘

Dependency Rule: Feature modules never import Data and never import sibling features.

Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

• Feature modules import Domain + DesignSystem only (never Data, never sibling features)
• App target is the convergence point and owns DependencyContainer, concrete coordinators, and Route Shell wiring
• Domain stays pure Swift and defines models plus repository, *Coordinating, ErrorRouting, and AppError contracts
• Data owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
• Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
• ViewModels call repository protocols directly (no default use-case/interactor layer)

When to Apply

Reference these guidelines when:

• Migrating from deprecated SwiftUI APIs (ObservableObject, NavigationView, old onChange)
• Restructuring state management to use @Observable ViewModels
• Adding @Equatable diffing to views for performance
• Decomposing large views into 10-node maximum bodies
• Refactoring navigation to coordinator + route shell pattern
• Refactoring to Domain/Data/Feature/App package boundaries
• Setting up dependency injection through DependencyContainer
• Improving list/collection scroll performance
• Replacing manual Task management with .task(id:) and cancellable loading

Non-Negotiable Constraints (iOS 26 / Swift 6.2)

• @Observable ViewModels/coordinators, ObservableObject / @Published never
• NavigationStack is owned by App-target route shells and coordinators
• @Equatable macro on every view, AnyView never
• Domain defines repository/coordinator/error-routing protocols; no framework-coupled I/O
• No dedicated use-case/interactor layer; ViewModels call repository protocols directly
• Views never access repositories directly

Rule Categories by Priority

Quick Reference

1. View Identity & Diffing (CRITICAL)

• diff-equatable-views - Add @Equatable macro to every SwiftUI view
• diff-closure-skip - Use @EquatableIgnored for closure properties
• diff-identity-stability - Use stable O(1) identifiers in ForEach
• diff-printchanges-debug - Use _printChanges() to diagnose re-renders

2. API Modernization (CRITICAL)

• api-observable-macro - Migrate ObservableObject to @Observable macro
• api-navigationstack-migration - Replace NavigationView with NavigationStack
• api-onchange-signature - Migrate to new onChange signature
• api-environment-object-removal - Replace @EnvironmentObject with @Environment
• api-alert-confirmation-dialog - Migrate Alert to confirmationDialog API
• api-list-foreach-identifiable - Replace id: .self with Identifiable conformance
• api-toolbar-migration - Replace navigationBarItems with toolbar modifier

3. State Architecture (CRITICAL)

• state-scope-minimization - Minimize state scope to nearest consumer
• state-derived-over-stored - Use computed properties over redundant @State
• state-binding-extraction - Extract @Binding to isolate child re-renders
• state-remove-observation - Migrate @ObservedObject to @Observable tracking
• state-onappear-to-task - Replace onAppear closures with .task modifier
• state-stateobject-placement - Migrate @StateObject to @State with @Observable

4. View Composition (HIGH)

• view-extract-subviews - Extract subviews for diffing checkpoints
• view-eliminate-anyview - Replace AnyView with @ViewBuilder or generics
• view-computed-to-struct - Convert computed view properties to struct views
• view-modifier-extraction - Extract repeated modifiers into custom ViewModifiers
• view-conditional-content - Use Group or conditional modifiers over conditional views
• view-preference-keys - Replace callback closures with PreferenceKey
• view-body-complexity - Reduce view body to maximum 10 nodes