data-migration
Plan and implement CRM Orbit data migrations for Automerge snapshots and Drizzle persistence, including schema additions, event payload changes, and backfills. Use when adding/removing fields, changing persisted structures, or introducing new events that require compatibility or data backfill.
When & Why to Use This Skill
This Claude skill automates the planning and implementation of complex data migrations for CRM Orbit, specifically handling Automerge snapshots and Drizzle persistence. It ensures data integrity through deterministic workflows, schema updates, and backfill logic while maintaining backward compatibility and preserving event-log semantics.
Use Cases
- Schema Evolution: Seamlessly adding or removing fields in Drizzle/SQLite tables and Automerge snapshots while ensuring the persistence layer remains stable.
- Event Payload Updates: Managing changes to event structures by introducing new required fields and updating reducers to handle legacy data shapes.
- Deterministic Data Backfills: Implementing logic to derive new values from existing event history without mutating state directly, ensuring a reliable audit trail.
- Versioned State Handling: Adding versioned handling in the data load path to maintain compatibility between different snapshot formats during system upgrades.
| name | data-migration |
|---|---|
| description | Plan and implement CRM Orbit data migrations for Automerge snapshots and Drizzle persistence, including schema additions, event payload changes, and backfills. Use when adding/removing fields, changing persisted structures, or introducing new events that require compatibility or data backfill. |
Data Migration
Overview
Implement safe, deterministic migrations for CRM Orbit local persistence (Drizzle/SQLite) and Automerge snapshots while preserving event-log semantics.
Workflow
- Classify the change
- Schema-only (Drizzle table changes, snapshot fields)
- Event payload change (new fields required)
- Backfill required (existing data needs derived values)
- Update persistence
- Add Drizzle migrations for new columns/tables.
- Update persistence loader/serializer to accept old shapes and default new fields.
- Preserve snapshot compatibility
- If snapshot format changes, add versioned handling in load path.
- Keep encoding/decoding boundary locale-neutral.
- Backfill via events
- Emit migration events or deterministic backfill logic in reducers.
- Never mutate state directly or infer history from diffs.
- Verify
- Add/update reducer tests and persistence loader tests.
- Add event->state snapshot tests for migration paths.
Guardrails
- Automerge is source of truth.
- Event log is append-only and human-readable.
- Reducers remain pure and deterministic.
- Persistence remains dumb (no business rules).
- Persisted data stays locale-neutral.
Common files
CRMOrbit/automerge/schema.tsCRMOrbit/domains/persistence/*CRMOrbit/events/*,CRMOrbit/reducers/*CRMOrbit/tests/*