Fetches axiom-swiftui-debugging-diag from charleswiltgen/axiom and configures it for Cursor.
3
Select Cursor when prompted
The CLI shows a list of agents. Use arrow keys and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ────────────────
│ · Cline · Codex · Goose · Windsurf
│ ●Cursor(selected)
│ · Cursor · Aider · Continue
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/axiom-swiftui-debugging-diag
Restart Cursor to activate axiom-swiftui-debugging-diag. Access via /axiom-swiftui-debugging-diag in your agent's command palette.
⚠
Security 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 environment. Always review source, verify the publisher, and test in isolation before production.
"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 setupxcodebuild -version# Must be Xcode 26+ for SwiftUI Instrument# 2. Build in Release mode for profilingxcodebuild build -scheme YourScheme -configuration Release
# 3. Clear derived data if investigating preview issuesrm-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:
structMyView:View{@Stateprivatevar count =0@Environment(AppModel.self)privatevar model
var body:someView{let_=Self._printChanges()// Add temporarilyVStack{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:
"@self changed" when you don't expect
Parent recreating view unnecessarily
Check parent's state management
Property shows changed but you didn't change it
Indirect dependency (reading from object that changed)
Pattern D2: Use Instruments to trace
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
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 conditionif 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 changesDetailView().id(item.id +"-\(isEditing)")// ID changes with isEditing// ✅ FIX: Stable IDDetailView().id(item.id)// Stable ID
Find: Search codebase for .id( — check if ID values change
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 projectgrep-r"\.environment("--include
Implementation Guide
Prerequisites
›Claude Desktop or compatible AI client with skill support
›Clear understanding of task or problem to solve
›Willingness to iterate and refine outputs
Time Estimate
15-45 minutes depending on use case complexity
Steps
1Install skill using provided installation command
2Test with simple use case relevant to your work
3Evaluate output quality and relevance
4Iterate on prompts to improve results
5Integrate into regular workflow if valuable
Common Pitfalls
⚠Expecting perfect results without iteration
⚠Not providing enough context in prompts
⚠Using skill for tasks outside its intended scope
⚠Accepting outputs without review and validation
Best Practices
✓ Do
+Start with clear, specific prompts
+Provide relevant context and constraints
+Review and refine all outputs before using
+Iterate to improve output quality
+Document successful prompt patterns
✗ Don't
−Don't use without understanding skill limitations
−Don't skip validation of outputs
−Don't share sensitive information in prompts
−Don't expect skill to replace human judgment
💡 Pro Tips
★Be specific about desired format and style
★Ask for multiple options to choose from
★Request explanations to understand reasoning
★Combine AI efficiency with human expertise
When to Use This
✓ Use when
Use when skill capabilities match your task, clear ROI on time saved, and you can validate outputs. Best for repetitive tasks, learning, and quality improvement.
✗ Avoid when
Avoid when task requires deep expertise you can't validate, involves sensitive decisions, or when learning process is more valuable than speed of completion.
Learning Path
1Familiarize yourself with skill capabilities and limitations
2Start with low-risk, non-critical tasks
3Progress to more complex and valuable use cases
4Build expertise through regular use and experimentation
