agents in

skills/software/database-migrations.md

@@ -0,0 +1,45 @@
+# Database Migrations and Data Evolution
+
+## Purpose
+
+Change schemas and data safely while protecting compatibility, correctness, rollout reliability, and recovery options.
+
+## When to use
+
+- Adding, removing, or changing database schema
+- Backfilling or transforming data
+- Introducing compatibility windows between old and new code
+- Planning rollout for data-sensitive changes
+
+## Inputs to gather
+
+- Current schema, access patterns, and data volume
+- Migration tooling and deployment model
+- Compatibility requirements across services, jobs, or clients
+- Rollback constraints and data recovery options
+
+## How to work
+
+- Prefer staged migrations when compatibility matters: expand, backfill, switch reads or writes, then contract.
+- Minimize lock risk, data loss risk, and long-running migration risk.
+- Consider how old and new code will coexist during rollout.
+- Define verification steps for schema state and critical data correctness.
+- Document irreversible steps and operator actions clearly.
+
+## Output expectations
+
+- Safe migration plan or implementation
+- Compatibility and rollout notes
+- Verification and rollback considerations
+
+## Quality checklist
+
+- The migration is safe for the repository's deployment model.
+- Data correctness is protected during and after rollout.
+- Backwards and forwards compatibility are considered when needed.
+- Irreversible or risky steps are made explicit.
+
+## Handoff notes
+
+- Call out sequencing requirements across application code, migrations, and background jobs.
+- Pair with release/change summary and technical docs when operators or teammates need a clear rollout path.