Safe Migrations

Read anti-ai-writing before drafting plans, notices, or reports. Distinguish planning, implementation, live execution, and removal. Preserve authorization already given, but do not infer production writes, consumer notifications, destructive execution, or publication from a request to prepare a migration.

1. Establish the contract and consumers

Read repository instructions, current implementation, supported versions, consumers, deployment topology, tests, and relevant operational evidence. Verify tool, database, and framework semantics against their actual versions and official documentation. Define the reason for the transition, required replacement behavior, scope, owners, and accepted breaking changes. Retirement without a replacement can be intentional; record that decision rather than inventing an alternative or deadline.

Trace published interfaces, dynamic names, configuration, generated clients, jobs, integrations, offline clients, persisted formats, and external consumers. Search results and low traffic alone do not establish absence of dependency. Record what is verified, unknown, and outside available visibility.

Compare old/new behavior across inputs, outputs, errors, defaults, identity, ordering, authorization, tenant scope, and side effects. Separate supported contracts from incidental observations, but investigate observable behavior consumers may rely on. An additive field, new enum value, or changed default can still break a consumer. Apply the project's versioning and support policy; use semantic versioning only where that is the established public version contract.

2. Plan independently verifiable stages

Use agent-planning for consequential multi-stage work. Record phase order, compatible version combinations, success evidence, abort criteria, recovery actions, and the point beyond which reverting code is insufficient. Keep the plan proportional; a local dependency upgrade does not need a service cutover ceremony. For persisted data, read database and backfill guidance. For database operations, verify version-specific lock and rewrite behavior and record representative rehearsal evidence before advancing. Prepare actionable recovery for every cutover, not only database changes. When reversal is impossible, define the restoration or forward-repair path and identify the irreversible boundary.

Choose a transition based on the actual boundary:

Avoid introducing flags, dual writes, or permanent adapters without a concrete need. When used, define their ownership, consistency rules, rollback limits, and eventual removal conditions. Shadow execution must not duplicate external writes or other side effects. Isolate cohorts and telemetry without leaking tenant data.

For public deprecation, prepare a notice with reason, affected versions, supported replacement or retirement outcome, migration steps, and accepted support/removal dates. Do not invent a notice period or announce an unapproved deadline. Provide tooling or examples proportional to consumer effort. Draft locally; publish or contact owners only under applicable authorization.

3. Implement and verify the transition

Preserve unrelated work and make stages reviewable. Confirm compatibility across old/new producers and consumers, rollout order, mixed versions, retries, and relevant failure paths. Use test-authoring for independently justified expectations. Verify migrations against representative existing state, not just clean installation. Reconcile new-install and upgraded-system behavior. Rehearse first with representative data in an isolated safe environment. Shared staging execution requires separate authorization and cannot replace that rehearsal.

Tie operational evidence to the exact candidate, schema/data state, environment, and cohort. Define parity checks that detect missing records, altered identities, ordering, or unauthorized access rather than relying only on totals. Investigate differences before promoting a stage.

Before cutover, safely verify the recovery procedure against the candidate and representative state. Record the observed result, including restoration or forward repair when reversal is impossible. A documented but untested procedure does not satisfy this gate. If required verification fails or cannot be performed safely, report the missing evidence and hold cutover; continue only independent authorized preparation. Do not substitute confidence for recovery evidence.

Use ci-cd-workflows for staged automation and code-review for consequential migration review when independence is available and authorized. A passing suite alone does not authorize live cutover or establish consumer readiness.

4. Remove only after readiness is supported

Before contracting or deleting, verify migrated consumers, disabled old writers, completed reconciliation, and support obligations. Choose a representative observation window based on actual usage cycles, including scheduled jobs and offline clients. Account for telemetry gaps and dormant consumers; zero observed requests is not proof of zero dependency. Keep recovery viable until the accepted removal boundary.

Remove retired code, configuration, jobs, flags, and obsolete tests within scope. Preserve tests for continuing contracts, required historical migrations, and useful migration/version history. Do not delete records merely because active usage ended. Resolve unknown consumers or obtain an explicit risk decision before destructive work.

Report implemented stages separately from executed migration, verified cutover, and completed retirement. State remaining dependencies, irreversible effects, and verification limits. Commit, push, and publication require authorization through git-delivery.