---
name: swiftui-component-audit-workflow
description: Audit and repair SwiftUI code toward self-contained declarative components, local reactive state, framework-native data flow, and simple reusable view interfaces. Use when an existing SwiftUI feature has external ViewModels, injected collaborators, imperative coordination, duplicated state, environment dumping, or unclear component ownership.
---

# SwiftUI Component Audit Workflow

## Purpose

Audit or repair a SwiftUI feature without importing AppKit, UIKit, or generic imperative architecture into a declarative view tree. SwiftUI components stand on their own: they render from explicit values and framework state, own local presentation state, and express user intent through narrow actions. A feature service, when needed, is a direct concrete owner of one capability rather than a wrapper stack.

## SwiftData And SwiftUI Rule

Keep SwiftData directly integrated with SwiftUI through `modelContainer`, environment `modelContext`, `@Query`, model objects, and narrow bindings. Do not insert repositories, stores, service mirrors, DTO mirrors, ViewModel caches, or other abstraction layers between SwiftData and SwiftUI. Hand persistence-specific decisions to `swiftdata-workflow`.

## When To Use

- Use for a SwiftUI architecture review, component audit, repair, or refactor.
- Use when reusable views receive ViewModels, stores, services, managers, coordinators, or other collaborating objects.
- Use when state is duplicated, a router or coordinator shadows SwiftUI navigation, or an environment becomes a dependency dump.
- Use when a team needs concrete good/bad SwiftUI examples before implementing a feature.
- Hand SwiftData persistence decisions to `swiftdata-workflow`, app and scene ownership to `swiftui-app-architecture-workflow`, and execution to the Xcode build or testing workflows.

## Single-Path Workflow

1. Read the relevant Apple documentation through `explore-apple-swift-docs` before proposing a repair.
2. Inventory each view's stored properties, local state, environment reads, preferences, focus, commands, and outward actions.
3. Classify every dependency:
   - component input: value, narrow binding, or action closure
   - component-local state: `@State`, derived value, or locally owned `@Observable` state
   - hierarchy context: existing or custom environment value/action
   - upward layout or presentation fact: preference key
   - active command context: focus or focused value
   - direct persistence state: `ModelContainer`, `modelContext`, `@Query`, model object, or narrow binding
   - non-SwiftUI boundary: networking, import/export, migration, testing, or server sync
   - direct concrete feature service: one capability or cohesive related group with a named app or scene lifecycle owner
4. Report a finding for every reusable view that accepts an external ViewModel, store, coordinator, manager, service, or observable collaborator.
5. Report a finding for every umbrella app service, forwarding service facade, repository/protocol/adapter chain, or service that has no direct capability boundary.
6. Repair from the narrowest honest mechanism outward:
   - replace collaborators with values, bindings, and actions
   - move local presentation state into the owning view
   - use an existing environment action before adding a custom action
   - add a custom environment value or action only for a dynamic or broadly reused hierarchy capability
   - use preferences only for descendant-to-ancestor publication
   - restore direct SwiftData integration when persistence is being mirrored
   - collapse forwarding layers into the concrete feature service that owns the real capability
   - install that service in environment only when independent descendants need direct invocation or observation
7. Remove explicit initializers that only duplicate the synthesized memberwise initializer.
8. Re-audit the changed component boundaries and hand off for build, preview, or tests.

## Inputs

- `repository`: target repository or feature path.
- `mode`: `audit` for findings only, or `repair` for implementation.
- `scope`: optional files, feature, scene, or component name.
- `platform_context`: optional iOS, iPadOS, macOS, or mixed context.

## Outputs

- component inventory and declared ownership boundary
- findings ordered by severity with the violated component rule
- a before/after state-flow description
- exact repair plan or completed edits
- documented SwiftUI behavior relied on
- validation and handoff path

## Guards and Stop Conditions

- Do not recommend external ViewModels as a SwiftUI component shape.
- Do not treat values, bindings, and action closures as dependency injection; they are a declarative component interface.
- Do not pass collaborating objects between reusable views.
- Do not replace a documented SwiftUI environment action with an application router or coordinator.
- Do not add a custom environment action when a local action is sufficient; do add one when a dynamic or broadly shared hierarchy capability honestly needs it.
- Do not retain an AppService, repository, protocol, adapter, or wrapper layer that only forwards to another service. Keep the direct concrete feature service, and use a protocol only for a demonstrated alternate implementation or isolated test boundary.
- Do not use preference keys as a general state bus.
- Do not insert repositories, stores, DTO mirrors, service mirrors, or view-model caches between SwiftData and SwiftUI.
- Prefer memberwise initializers; an explicit initializer needs real behavior beyond stored-property assignment.
- Stop and surface a broader app, scene, persistence, or navigation ownership decision rather than hiding it in a local refactor.

## Fallbacks and Handoffs

- Recommend `swiftui-app-architecture-workflow` for app, scene, command, focus, environment, or navigation ownership decisions.
- Recommend `swiftdata-workflow` for persistence integration or migration decisions.
- Recommend `explore-apple-swift-docs` for primary documentation lookup.
- Recommend `xcode-build-run-workflow` for previews, build, run, project membership, or guarded mutations.
- Recommend `xcode-testing-workflow` for Swift Testing, XCTest, XCUITest, or test diagnosis.

## Customization

Use `references/customization-flow.md`. This workflow has no runtime-enforced knobs; keep audits grounded in the repository and Apple documentation.

## References

- `references/component-rules-and-examples.md`
- `references/audit-checklist.md`
- `references/customization-flow.md`
- Recommend `swiftui-app-architecture-workflow/references/snippets/apple-xcode-project-core.md` when the target repo needs durable Apple project policy.

### Script Inventory

- `scripts/customization_config.py`