Schema Evolution Planner

Plan safe, staged database schema changes across application code, backfills, and cutovers.

Scope: Expand-contract and compatibility planning for live systems. NOT for greenfield schema design (database-architect) or DBA operations.

Canonical Vocabulary

Term	Definition
expand	Additive schema change compatible with existing code
backfill	Data migration that populates new structures from old data
dual-write	Temporarily writing old and new representations
dual-read	Temporarily reading from both old and new representations
cutover	The point where traffic or logic switches to the new path
contract	Removal of deprecated schema after compatibility window closes
compatibility window	Period where old and new code must both work
invariant	Condition that must remain true during migration
shadow column	New field added beside the old field during migration
rollback point	Last safe state that can be restored without data loss

Dispatch

$ARGUMENTS	Mode
`plan <change>`	Build the full migration sequence
`review <migration or rollout>`	Audit an existing evolution plan
`backfill <change>`	Design the data backfill strategy
`cutover <change>`	Plan read or write switchover
`deprecate <change>`	Plan the contract and removal stage
Natural language about zero-downtime schema changes	Auto-detect the closest mode
Empty	Show the mode menu with examples

Mode Menu


plan rename users.username to handle
review migration plan for orders status enum change
backfill new account_id on invoices
cutover reads to new customer_profile table
deprecate legacy address columns

#	Mode	Example
1	Plan	`plan rename users.username to handle`
2	Review	`review migration plan for orders status enum change`
3	Backfill	`backfill new account_id on invoices`
4	Cutover	`cutover reads to new customer_profile table`
5	Deprecate	`deprecate legacy address columns`

When to Use

Renaming columns or tables in a live system
Splitting or merging tables without downtime
Adding required fields to existing tables
Introducing new identifiers or foreign keys gradually
Coordinating schema changes with multiple application deploys

Classification Logic

Use this as the classification gate before choosing a mode:

If the task is fresh schema design, data modeling, or table design from scratch, route to
```
database-architect
```
.
If the task is query tuning, index tuning, vacuuming, replication, or database administration, do not use this skill.
If the task is release orchestration, artifact promotion, or rollout topology beyond schema sequencing, route to
```
release-pipeline-architect
```
.
If the task is an application feature change with no compatibility window, use the application or framework skill instead.
If the prompt mixes rename-vs-redesign uncertainty, start in
```
plan
```
mode and explicitly decide whether the change is additive evolution or a broader redesign.

Instructions

Mode: Plan

Identify the current read paths, write paths, downstream consumers, and deployment order constraints.
Classify the change: rename, type change, split, merge, constraint hardening, or deletion.
Read
```
references/change-type-decision-matrix.md
```
to pick the safest expand-contract pattern for the change type.
Read
```
references/sample-rollout-sequences.md
```
if the change touches multiple deploys, readers, writers, or downstream consumers.
Write an expand-contract sequence with explicit checkpoints: expand, deploy compatibility code, backfill, validate invariants, cutover, then contract.
Define the compatibility window and what old and new code must tolerate during it.
Name the invariants that must be measured before moving to the next phase.
Present the plan using the relevant template from
```
references/output-templates.md
```
.

Mode: Review

Read the migration plan, migration files, and any rollout notes.

Read

references/migration-failure-modes.md

and

references/change-type-decision-matrix.md

Check for hidden destructive steps, missing compatibility windows, or missing rollback points.
Flag assumptions about data quality, backfill runtime, and consumer readiness.
Rank findings by severity.
Present findings using the review template in
```
references/output-templates.md
```
.

Mode: Backfill

Define the source of truth and target population logic.
Make the backfill idempotent and chunkable.
Read
```
references/migration-failure-modes.md
```
for duplicate-write, drift, and reconciliation hazards.
Specify batching strategy, retry behavior, progress tracking, and reconciliation checks.
Decide whether dual-write is required while the backfill runs.
Present the plan using the backfill template in
```
references/output-templates.md
```
.

Mode: Cutover

Separate write cutover from read cutover when they do not need to happen together.
Define the exact success checks before switching traffic or logic.

Read

references/sample-rollout-sequences.md

and

references/migration-failure-modes.md

for abort and rollback patterns.

Keep a rollback point until the new path is proven stable.
Present the cutover checklist using
```
references/output-templates.md
```
.

Mode: Deprecate

Verify no live code, jobs, or consumers still depend on the old structure.
Remove writes first, then reads, then the deprecated schema.
Record the evidence that the compatibility window is closed.
Present evidence and removal ordering using the deprecate template in
```
references/output-templates.md
```
.

Output Requirements

Every plan must include expand, compatibility, validation, cutover, and contract stages.
State the invariants to check between stages.
Name the rollback point and the evidence needed to advance.

Critical Rules

Never remove or repurpose a live field before the compatibility window closes.
Every backfill must be idempotent and restartable.
Cutovers must define success and abort criteria in advance.
Destructive changes belong only in the contract stage.
If the change is really a fresh schema design problem, route it to database-architect.

Scaling Strategy

Complexity	Strategy
Small	Use a single additive compatibility path for simple renames, nullable adds, or shadow-column introductions.
Medium	Use explicit staged execution: expand, deploy compatibility logic, backfill in chunks, validate, cut over, then contract.
Large	Treat the change as a rollout program with separate read and write cutovers, evidence gates, and phased consumer movement.

Progressive Disclosure

Read reference files as indicated by the active mode instead of loading everything at once.
Load
```
references/change-type-decision-matrix.md
```
on demand for change classification and ambiguity handling.
Load
```
references/migration-failure-modes.md
```
on demand for reviews, backfills, and cutovers.
Load
```
references/sample-rollout-sequences.md
```
on demand for multi-phase execution planning.
Load
```
references/output-templates.md
```
on demand when presenting the final response.

Reference File Index

File	Purpose	When to Read
`references/change-type-decision-matrix.md`	Maps schema change types to safe evolution patterns, compatibility windows, and red flags	Any `plan` or `review` request
`references/migration-failure-modes.md`	Catalog of common rollout, backfill, and cutover failure modes with mitigations	`review` , `backfill` , or `cutover` work
`references/sample-rollout-sequences.md`	Reference expand-contract sequences for common migration shapes	Multi-phase `plan` or `cutover` work
`references/output-templates.md`	Standard response templates for plans, reviews, backfills, cutovers, and deprecations	Presenting final output in any mode

Scope Boundaries

IS for: zero-downtime renames, splits, merges, backfills, staged cutovers, compatibility sequencing.

NOT for: greenfield schema modeling, query tuning, or database administration.

schema-evolution-planner

NPX Install

Tags

SKILL.md Content