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