SwiftUI Debugging Diagnostics

When to Use This Diagnostic Skill

Use this skill when:

• Basic troubleshooting failed — Applied axiom-swiftui-debugging skill patterns but issue persists
• Self._printChanges() shows unexpected patterns — View updating when it shouldn't, or not updating when it should
• Intermittent issues — Works sometimes, fails other times ("heisenbug")
• Complex dependency chains — Need to trace data flow through multiple views/models
• Performance investigation — Views updating too often or taking too long
• Preview mysteries — Crashes or failures that aren't immediately obvious

FORBIDDEN Actions

Under pressure, you'll be tempted to shortcuts that hide problems instead of diagnosing them. NEVER do these:

❌ Guessing with random @State/@Observable changes

• "Let me try adding @Observable here and see if it works"
• "Maybe if I change this to @StateObject it'll fix it"

❌ Adding .id(UUID()) to force updates

• Creates new view identity every render
• Destroys state preservation
• Masks root cause

❌ Using ObservableObject when @Observable would work (iOS 17+)

• Adds unnecessary complexity
• Miss out on automatic dependency tracking

❌ Ignoring intermittent issues ("works sometimes")

• "I'll just merge and hope it doesn't happen in production"
• Intermittent = systematic bug, not randomness

❌ Shipping without understanding

• "The fix works, I don't know why"
• Production is too expensive for trial-and-error

Mandatory First Steps

Before diving into diagnostic patterns, establish baseline environment:

# 1. Verify Instruments setup
xcodebuild -version  # Must be Xcode 26+ for SwiftUI Instrument

# 2. Build in Release mode for profiling
xcodebuild build -scheme YourScheme -configuration Release

# 3. Clear derived data if investigating preview issues
rm -rf ~/Library/Developer/Xcode/DerivedData

Time cost: 5 minutes Why: Wrong Xcode version or Debug mode produces misleading profiling data

---

Diagnostic Decision Tree

SwiftUI view issue after basic troubleshooting?
│
├─ View not updating?
│  ├─ Basic check: Add Self._printChanges() temporarily
│  │  ├─ Shows "@self changed" → View value changed
│  │  │  └─ Pattern D1: Analyze what caused view recreation
│  │  ├─ Shows specific state property → That state triggered update
│  │  │  └─ Verify: Should that state trigger update?
│  │  └─ Nothing logged → Body not being called at all
│  │     └─ Pattern D3: View Identity Investigation
│  └─ Advanced: Use SwiftUI Instrument
│     └─ Pattern D2: SwiftUI Instrument Investigation
│
├─ View updating too often?
│  ├─ Pattern D1: Self._printChanges() Analysis
│  │  └─ Identify unnecessary state dependencies
│  └─ Pattern D2: SwiftUI Instrument → Cause & Effect Graph
│     └─ Trace data flow, find broad dependencies
│
├─ Intermittent issues (works sometimes)?
│  ├─ Pattern D3: View Identity Investigation
│  │  └─ Check: Does identity change unexpectedly?
│  ├─ Pattern D4: Environment Dependency Check
│  │  └─ Check: Environment values changing frequently?
│  └─ Reproduce in preview 30+ times
│     └─ If can't reproduce: Likely timing/race condition
│
└─ Preview crashes (after basic fixes)?
    ├─ Pattern D5: Preview Diagnostics (Xcode 26)
    │  └─ Check diagnostics button, crash logs
    └─ If still fails: Pattern D2 (profile preview build)

---

Diagnostic Patterns

Pattern D1: Self._printChanges() Analysis

Time cost: 5 minutes

Symptom: Need to understand exactly why view body runs

When to use:

• View updating more often than expected
• View not updating when it should
• Verifying dependencies after refactoring

Technique:

struct MyView: View {
    @State private var count = 0
    @Environment(AppModel.self) private var model

    var body: some View {
        let _ = Self._printChanges()  // Add temporarily

        VStack {
            Text("Count: \(count)")
            Text("Model value: \(model.value)")
        }
    }
}

Output interpretation:

# Scenario 1: View parameter changed
MyView: @self changed
→ Parent passed new MyView instance
→ Check parent code - what triggered recreation?

# Scenario 2: State property changed
MyView: count changed
→ Local @State triggered update
→ Expected if you modified count

# Scenario 3: Environment property changed
MyView: @self changed  # Environment is part of @self
→ Environment value changed (color scheme, locale, custom value)
→ Pattern D4: Check environment dependencies

# Scenario 4: Nothing logged
→ Body not being called
→ Pattern D3: View identity investigation

Common discoveries:

1. "@self changed" when you don't expect

   • Parent recreating view unnecessarily
   • Check parent's state management

2. Property shows changed but you didn't change it

   • Indirect dependency (reading from object that changed)
   • Pattern D2: Use Instruments to trace

3. Multiple properties changing together

   • Broad dependency (e.g., reading entire array when only need one item)
   • Fix: Extract specific dependency

Verification:

• Remove Self._printChanges() call before committing
• Never ship to production with this code

Cross-reference: For complex cases, use Pattern D2 (SwiftUI Instrument)

---

Pattern D2: SwiftUI Instrument Investigation

Time cost: 25 minutes

Symptom: Complex update patterns that Self._printChanges() can't fully explain

When to use:

• Multiple views updating when one should
• Need to trace data flow through app
• Views updating but don't know which data triggered it
• Long view body updates (performance issue)

Prerequisites:

• Xcode 26+ installed
• Device updated to iOS 26+ / macOS Tahoe+
• Build in Release mode

Steps:

1. Launch Instruments (5 min)

# Build Release
xcodebuild build -scheme YourScheme -configuration Release

# Launch Instruments
# Press Command-I in Xcode
# Choose "SwiftUI" template

2. Record Trace (3 min)

• Click Record button
• Perform the action that triggers unexpected updates
• Stop recording (10-30 seconds of interaction is enough)

3. Analyze Long View Body Updates (5 min)

• Look at Long View Body Updates lane
• Any orange/red bars? Those are expensive views
• Click on a long update → Detail pane shows view name
• Right-click → "Set Inspection Range and Zoom"
• Switch to Time Profiler track
• Find your view in call stack
• Identify expensive operation (formatter creation, calculation, etc.)

Fix: Move expensive operation to model layer, cache result

4. Analyze Unnecessary Updates (7 min)

• Highlight time range of user action (e.g., tapping favorite button)
• Expand hierarchy in detail pane
• Count updates — more than expected?
• Hover over view → Click arrow → "Show Cause & Effect Graph"

5. Interpret Cause & Effect Graph (5 min)

Graph nodes:

[Blue node] = Your code (gesture, state change, view body)
[System node] = SwiftUI/system work
[Arrow labeled "update"] = Caused this update
[Arrow labeled "creation"] = Caused view to appear

Common patterns:

# Pattern A: Single view updates (GOOD)
[Gesture] → [State Change in ViewModelA] → [ViewA body]

# Pattern B: All views update (BAD - broad dependency)
[Gesture] → [Array change] → [All list item views update]
└─ Fix: Use granular view models, one per item

# Pattern C: Cascade through environment (CHECK)
[State Change] → [Environment write] → [Many view bodies check]
└─ If environment value changes frequently → Pattern D4 fix

Click on nodes:

• State change node → See backtrace of where value was set
• View body node → See which properties it read (dependencies)

Verification:

• Record new trace after fix
• Compare before/after update counts
• Verify red/orange bars reduced or eliminated

Cross-reference: axiom-swiftui-performance skill for detailed Instruments workflows

---

Pattern D3: View Identity Investigation

Time cost: 15 minutes

Symptom: @State values reset unexpectedly, or views don't animate

When to use:

• Counter resets to 0 when it shouldn't
• Animations don't work (view pops instead of animates)
• ForEach items jump around
• Text field loses focus

Root cause: View identity changed unexpectedly

Investigation steps:

1. Check for conditional placement (5 min)

// ❌ PROBLEM: Identity changes with condition
if showDetails {
    CounterView()  // Gets new identity each time showDetails toggles
}

// ✅ FIX: Use .opacity()
CounterView()
    .opacity(showDetails ? 1 : 0)  // Same identity always

Find: Search codebase for views inside if/else that hold state

2. Check .id() modifiers (5 min)

// ❌ PROBLEM: .id() changes when data changes
DetailView()
    .id(item.id + "-\(isEditing)")  // ID changes with isEditing

// ✅ FIX: Stable ID
DetailView()
    .id(item.id)  // Stable ID

Find: Search codebase for .id( — check if ID values change

3. Check ForEach identifiers (5 min)

// ❌ WRONG: Index-based ID
ForEach(Array(items.enumerated()), id: \.offset) { index, item in
    Text(item.name)
}

// ❌ WRONG: Non-unique ID
ForEach(items, id: \.category) { item in  // Multiple items per category
    Text(item.name)
}

// ✅ RIGHT: Unique, stable ID
ForEach(items, id: \.id) { item in
    Text(item.name)
}

Find: Search for ForEach — verify unique, stable IDs

Fix patterns:

Issue	Fix
View in conditional	Use .opacity() instead
.id() changes too often	Use stable identifier
ForEach jumping	Use unique, stable IDs (UUID or server ID)
State resets on navigation	Check NavigationStack path management

Verification:

• Add Self._printChanges() — should NOT see "@self changed" repeatedly
• Animations should now work smoothly
• @State values should persist

---

Pattern D4: Environment Dependency Check

Time cost: 10 minutes

Symptom: Many views updating when unrelated data changes

When to use:

• Cause & Effect Graph shows "Environment" node triggering many updates
• Slow scrolling or animation performance
• Unexpected cascading updates

Root cause: Frequently-changing value in environment OR too many views reading environment

Investigation steps:

1. Find environment writes (3 min)

# Search for environment modifiers in current project
grep -r "\.environment(" --include
how to use axiom-swiftui-debugging-diag
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use axiom-swiftui-debugging-diag on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add axiom-swiftui-debugging-diag
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/charleswiltgen/axiom --skill axiom-swiftui-debugging-diagcopy
The skills CLI fetches axiom-swiftui-debugging-diag from GitHub repository charleswiltgen/axiom and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/axiom-swiftui-debugging-diag
Reload or restart Cursor to activate axiom-swiftui-debugging-diag. Access the skill through slash commands (e.g., /axiom-swiftui-debugging-diag) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?