Metadata

name: core-data-expert
description: Expert Core Data guidance (iOS/macOS): stack setup, fetch requests & NSFetchedResultsController, saving/merge conflicts, threading & Swift Concurrency, batch operations & persistent history, migrations, performance, and NSPersistentCloudKitContainer/CloudKit sync.

Core Data Expert

Fast, production-oriented guidance for building correct, performant Core Data stacks and fixing common crashes.

Agent behavior contract (follow these rules)

Determine OS/deployment target when advice depends on availability (iOS 14+/17+ features, etc.).
Identify the context type before proposing fixes: view context (UI) vs background context (heavy work).
Recommend NSManagedObjectID for cross-context/cross-task communication; never pass NSManagedObject instances across contexts.
Prefer lightweight migration when possible; use staged migration (iOS 17+) for complex changes.
When recommending batch operations, verify persistent history tracking is enabled (often required for UI updates).
For CloudKit integration, remind developers that Production schema is immutable.
Reference WWDC/external resources sparingly; prefer this skill’s references/.

Clarify the goal: setup, bugfix, migration, performance, CloudKit?
Collect minimal facts:
- platform + deployment target
- store type (SQLite / in-memory) and whether CloudKit is enabled
- context involved (view vs background) and whether Swift Concurrency is in use
- exact error message + stack trace/logs
Branch immediately:
- threading/crash → focus on context confinement + NSManagedObjectID handoff
- migration error → identify model versions + migration strategy
- batch ops not updating UI → persistent history tracking + merge pipeline

Stack setup / merge policies / contexts → references/stack-setup.md
Saving patterns → references/saving.md
Fetch requests / list updates / aggregates → references/fetch-requests.md
Traditional threading (perform/performAndWait, object IDs) → references/threading.md
Swift Concurrency (async/await, actors, Sendable, DAOs) → references/concurrency.md
Batch insert/delete/update → references/batch-operations.md
Persistent history tracking + “batch ops not updating UI” → references/persistent-history.md
Model configuration (constraints, validation, derived/composite, transformables) → references/model-configuration.md
Schema migration (lightweight/staged/deferred) → references/migration.md
CloudKit integration & debugging → references/cloudkit-integration.md
Performance profiling & memory → references/performance.md
Testing patterns → references/testing.md
Terminology → references/glossary.md

“Failed to find a unique match for an NSEntityDescription” → references/testing.md (shared NSManagedObjectModel)
NSPersistentStoreIncompatibleVersionHashError → references/migration.md (versioning + migration)
Cross-context/threading exceptions (e.g. delete/update from wrong context) → references/threading.md and/or references/concurrency.md (use NSManagedObjectID)
Sendable / actor-isolation warnings around Core Data → references/concurrency.md (don’t “paper over” with @unchecked Sendable)
NSMergeConflict / constraint violations → references/model-configuration.md + references/stack-setup.md (constraints + merge policy)
Batch operations not updating UI → references/persistent-history.md + references/batch-operations.md
CloudKit schema/sync issues → references/cloudkit-integration.md
Memory grows during fetch → references/performance.md + references/fetch-requests.md

Confirm the context matches the work (UI vs background).
Ensure NSManagedObject instances never cross contexts; pass NSManagedObjectID instead.
If using batch ops, confirm persistent history tracking + merge pipeline.
If using constraints, confirm merge policy and conflict resolution strategy.
If performance-related, profile with Instruments and validate fetch batching/limits.