Core Data issues manifest as production crashes from schema mismatches, mysterious concurrency errors, performance degradation under load, and data corruption from unsafe migrations. Core principle 85% of Core Data problems stem from misunderstanding thread-confinement, schema migration requirements, and relationship query patterns—not Core Data defects.
Fetches axiom-core-data-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-core-data-diag
Restart Cursor to activate axiom-core-data-diag. Access via /axiom-core-data-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.
Core Data issues manifest as production crashes from schema mismatches, mysterious concurrency errors, performance degradation under load, and data corruption from unsafe migrations. Core principle 85% of Core Data problems stem from misunderstanding thread-confinement, schema migration requirements, and relationship query patterns—not Core Data defects.
Red Flags — Suspect Core Data Issue
If you see ANY of these, suspect a Core Data misunderstanding, not framework breakage:
Crash on production launch: "Unresolvable fault" after schema change
Thread-confinement error: "Accessing NSManagedObject on a different thread"
App suddenly slow after adding a User→Posts relationship
SwiftData app needs complex features; considering mixing Core Data alongside
Schema migration works in simulator but crashes on production
❌ FORBIDDEN "Core Data is broken, we need a different database"
Core Data handles trillions of records in production apps
Schema mismatches and thread errors are always developer code, not framework
Do not rationalize away the issue—diagnose it
Critical distinction Simulator deletes the database on each rebuild, hiding schema mismatch issues. Real devices keep persistent databases and crash immediately on schema mismatch. MANDATORY: Test migrations on real device with real data before shipping.
Mandatory First Steps
ALWAYS run these FIRST (before changing code):
// 1. Identify the crash/issue type// Screenshot the crash message and note:// - "Unresolvable fault" = schema mismatch// - "different thread" = thread-confinement// - Slow performance = N+1 queries or fetch size issues// - Data corruption = unsafe migration// Record: "Crash type: [exact message]"// 2. Check if it's schema mismatch// Compare these:let coordinator = persistentStoreCoordinator
let model = coordinator.managedObjectModel
let store = coordinator.persistentStores.first
// Get actual store schema version:do{let metadata =tryNSPersistentStoreCoordinator.metadataForPersistentStore( ofType:NSSQLiteStoreType, at: storeURL, options:nil)print("Store version identifier: \(metadata[NSStoreModelVersionIdentifiersKey]??"unknown")")// Get app's current model version:print("App model version: \(model.versionIdentifiers)")// If different = schema mismatch}catch{print("Schema check error: \(error)")}// Record: "Store version vs. app model: match or mismatch?"// 3. Check thread-confinement for concurrency errors// For any NSManagedObject access:print("Main thread? \(Thread.isMainThread)")print("Context concurrency type: \(context.concurrencyType.rawValue)")print("Accessing from: \(Thread.current)")// Record: "Thread mismatch? Yes/no"// 4. Profile relationship access for N+1 problems// In Xcode, run with arguments:// -com.apple.CoreData.SQLDebug 1// Check Console for SQL queries:// SELECT * FROM USERS; (1 query)// SELECT * FROM POSTS WHERE user_id = 1; (1 query per user = N+1!)// Record: "N+1 found? Yes/no, how many extra queries"// 5. Check SwiftData vs. Core Data confusionif#available(iOS 17.0,*){// If using SwiftData @Model + Core Data simultaneously:// Error: "Store is locked" or "EXC_BAD_ACCESS"// = trying to access same database from both layersprint("Using both SwiftData and Core Data on same store?")}// Record: "Mixing SwiftData + Core Data? Yes/no"
What this tells you
Schema mismatch → Proceed to Pattern 1 (lightweight migration decision)
Thread-confinement error → Proceed to Pattern 2 (async/await concurrency)
N+1 queries → Proceed to Pattern 3 (relationship prefetching)
SwiftData + Core Data conflict → Proceed to Pattern 4 (bridging)
Slow after migration → Proceed to Pattern 5 (testing safety)
MANDATORY INTERPRETATION
Before changing ANY code, identify ONE of these:
If crash is "Unresolvable fault" AND store/model versions differ → Schema mismatch (not user error)
If crash mentions "different thread" AND you're using DispatchQueue → Thread-confinement (not thread-safe design)
If performance degrades with relationship access → N+1 queries (check SQL log)
If SwiftData and Core Data code exist together → Conflicting data layers (architectural issue)
If migration test passes but production fails → Edge case in real data (testing gap)
If diagnostics are contradictory or unclear
STOP. Do NOT proceed to patterns yet
Add print statements to every NSManagedObject access (thread check)
Add -com.apple.CoreData.SQLDebug 1 and count SQL queries
Establish baseline: what's actually happening vs. what you assumed
Decision Tree
Core Data problem suspected?
├─ Crash: "Unresolvable fault"?
│ └─ YES → Schema mismatch (store ≠ app model)
│ ├─ Add new required field? → Pattern 1a (lightweight migration)
│ ├─ Remove field, rename, or change type? → Pattern 1b (heavy migration)
│ └─ Don't know how to fix? → Pattern 1c (testing safety)
│
├─ Crash: "different thread"?
│ └─ YES → Thread-confinement violated
│ ├─ Using DispatchQueue for background work? → Pattern 2a (async context)
│ ├─ Mixing Core Data with async/await? → Pattern 2b (structured concurrency)
│ └─ SwiftUI @FetchRequest causing issues? → Pattern 2c (@FetchRequest safety)
│
├─ Performance: App became slow?
│ └─ YES → Likely N+1 queries
│ ├─ Accessing user.posts in loop? → Pattern 3a (prefetching)
│ ├─ Large result set? → Pattern 3b (batch sizing)
│ └─ Just added relationships? → Pattern 3c (relationship tuning)
│
├─ Using both SwiftData and Core Data?
│ └─ YES → Data layer conflict
│ ├─ Need Core Data features SwiftData lacks? → Pattern 4a (drop to Core Data)
│ ├─ Already committed to SwiftData? → Pattern 4b (stay in SwiftData)
│ └─ Unsure which to use? → Pattern 4c (decision framework)
│
└─ Migration works locally but crashes in production?
└─ YES → Testing gap
├─ Didn't test with real data? → Pattern 5a (production testing)
├─ Schema change affects large dataset? → Pattern 5b (migration safety)
└─ Need verification before shipping? → Pattern 5c (pre-deployment checklist)
Common Patterns
Pattern Selection Rules (MANDATORY)
Apply ONE pattern at a time, starting with diagnostics
Always start with Mandatory First Steps — Identify the actual problem
Run decision tree — Narrow to specific pattern
Apply ONE pattern — Don't combine patterns
Test on real device — Simulator hides issues
Verify with migration test — Before deploying
FORBIDDEN
❌ Changing code without diagnostics
❌ Skipping real device testing
❌ Using simulator success as proof of migration safety
❌ Mixing multiple migration patterns
❌ Deploying migrations without pre-deployment verification
PRINCIPLE Core Data can automatically migrate simple schemas (additive changes) without data loss if done correctly.
✅ SAFE Lightweight Migrations
Adding new optional field: @NSManaged var nickname: String?
Adding new required field WITH default: Create attribute with default value
Renaming entity or attribute: Use mapping model with automatic mapping
Removing unused field: Just delete from model (data stays on disk, ignored)
❌ WRONG (Crashes production)
// BAD: Adding required field without migration@NSManagedvar userID:String// Required, no default// BAD: Assuming simulator = production// Works in simulator (deletes DB), crashes on real device// BAD: Modifying field type@NSManagedvar createdAt:Date// Was String, now Date// Core Data can't automatically convert
✅ CORRECT (Safe lightweight migration)
// 1. In Xcode: Editor → Add Model Version// Creates new .xcdatamodel version file// 2. In new version, add required field WITH default:@NSManagedvar userID:String=UUID().uuidString
// 3. Mark as current model version:// File Inspector → Versioned Core Data Model// Check "Current Model Version"// 4. Test:// Simulate old version: delete app, copy old database, run with new code// Real app loads → migration succeeded// 5. Deploy when confident
When this works
Adding optional fields (always safe)
Adding required fields WITH default values
Removing fields
Renaming entities/attributes with mapping model
When this FAILS (don't try lightweight)
Changing field type (String → Int)
Making optional field required (data has nulls, can't convert)
Complex relationship changes
Custom data transformations needed
Time cost 5-10 minutes for lightweight migration setup
Pattern 1b: Heavy Migration (Complex Schema Changes)
PRINCIPLE When lightweight migration won't work, use NSEntityMigrationPolicy for custom transformation logic.
Use when
Changing field types (String → Date)
Making optional required (need to populate existing nulls)
Complex relationship restructuring
Custom data transformations (e.g., split "firstName lastName" into separate fields)
›Access to product documentation and roadmap tools (Jira, Notion, etc.)
›Understanding of product management frameworks (RICE, Jobs-to-be-Done, etc.)
›Stakeholder contact information and communication channels
Time Estimate
30-60 minutes to see productivity improvements
Steps
1Install product management skill
2Start with user story generation for known feature
3Progress to competitive analysis: research 2-3 competitors
4Use for roadmap prioritization: apply RICE/ICE scoring
5Draft stakeholder communications and refine based on feedback
6Build template library for recurring PM tasks
7Share effective prompts with product team
Common Pitfalls
⚠Not validating competitive research—verify facts before sharing
⚠Accepting user stories without involving engineering team
⚠Over-relying on frameworks without qualitative judgment
⚠Not customizing outputs to company culture and communication style
⚠Skipping stakeholder validation of generated requirements
Best Practices
✓ Do
+Validate research and competitive analysis with real data
+Collaborate with engineering when generating technical requirements
+Customize frameworks and templates to your company context
+Use skill for first drafts, refine with stakeholder input
+Document successful prompt patterns for PM tasks
+Combine AI efficiency with human judgment and intuition
✗ Don't
−Don't publish competitive analysis without fact-checking
−Don't finalize user stories without engineering review
−Don't make prioritization decisions solely on AI scoring
−Don't skip customer validation of generated requirements
−Don't ignore company-specific context and culture
💡 Pro Tips
★Provide context: company goals, constraints, customer feedback
★Ask for alternatives: 'Show 3 ways to prioritize this roadmap'
★Request stakeholder-specific formatting: 'Executive summary vs. engineering spec'
★Use skill for 70% generation + 30% customization to company needs
When to Use This
✓ Use when
Use for user story writing, competitive research, roadmap prioritization, stakeholder communication, and PRD drafting. Best for reducing repetitive documentation and research work.
✗ Avoid when
Avoid for strategic product vision (requires deep customer empathy), pricing decisions (needs market and financial expertise), or when face-to-face customer discovery is more valuable than speed.
Learning Path
1Basic: user stories, feature specs, status updates
