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/.

First 60 seconds (triage template)

• 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

Routing map (pick the right reference fast)

• 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

Common errors → next best move

• “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

Verification checklist (when changing Core Data code)

• 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.

Reference files

• references/_index.md (navigation)

• references/stack-setup.md

• references/saving.md

• references/fetch-requests.md

• references/threading.md

• references/concurrency.md

• references/batch-operations.md

• references/persistent-history.md

• references/model-configuration.md

• references/migration.md

• references/cloudkit-integration.md

• references/performance.md

• references/testing.md

• references/glossary.md