agentleFS
S3n0001S3n0001/agent-skills/migrate-contracts-safely/SKILL.md

migrate-contracts-safely

Skill1 starsChanged 2 months agoMITView on GitHub

Move a schema, API, event, protocol, config, or dependency contract through expand, migrate, switch, verify, and contract phases with mixed-version safety and real rollback. Code slices use engineer-code-change.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    High-risk: add policy-required independent review, consumer discovery, representative rehearsal, longer compatibility preservation, and …

    line 16
  2. Distinctive:

    Use direct replacement only when every lean condition is evidenced.

    line 32
  3. Distinctive:

    Expand: add the new representation or behavior while old producers, consumers, and recovery versions remain valid.

    line 34
  4. Distinctive:

    Contract: remove the old path only after old consumers and rollback versions are gone, reconciliation closes, the recovery decision is …

    line 38
  5. Distinctive:

    Keep phases independently deployable.

    line 40
  6. Distinctive:

    Never let a default turn unconvertible data into plausible but wrong data.

    line 46
  7. Distinctive:

    Before a production backfill, writer or reader switch, schema enforcement, traffic cutover, old-path disablement, destructive contraction, …

    line 52

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Migrate Contracts Safely

Change a durable contract without losing data, stranding consumers, or making rollback fictional. A migration is a sequence of compatible states, not one diff or one deployment.

This skill is primary for the contract map, mixed-version guarantees, phase ordering, cutover criteria, rollback boundary, and retirement of the old path. Each local code slice runs under engineer-code-change with this skill owning its compatibility constraints. change-production-data-safely owns live backfills and record rewrites, release-production-changes owns candidate promotion, and engineer-reliable-data-pipelines owns delivery, replay, and time semantics. Local migration artifacts authorize no deployment, production access, backfill, cutover, or destructive contraction.

Choose proportionate depth

  • Lean: direct replacement only for a private contract with known consumers, truly atomic deployment or disposable state, and a verified recovery path.
  • Standard: explicit expand, migrate, switch, verify, and contract phases with mixed-version tests, resumable movement, reconciliation, and owned cleanup.
  • High-risk: add policy-required independent review, consumer discovery, representative rehearsal, longer compatibility preservation, and stronger cutover and irreversibility controls for public, externally consumed, high-volume, security-sensitive, data-destructive, cross-region, or weakly inventoried contracts.

Take coexistence windows, batch limits, performance gates, error thresholds, and approvals from actual consumers, service objectives, policy, baselines, and owners. An unknown value blocks that phase.

Map the contract and its traffic

  1. Identify current and target contracts, owner, producers, consumers, generated clients, persisted forms, caches, exports, jobs, pipeline stages, and external integrations.
  2. Determine deployment topology and version skew: which components update independently, which states can coexist, and what rollback versions may return.
  3. Inspect authorized metadata, sanitized samples, or safe replicas for volume, nulls, invalid legacy values, duplicates, constraints, retention, and concurrent writes.
  4. State invariants for meaning, correctness, availability, authorization, auditability, performance, and recovery.
  5. Record unknown consumers explicitly. Repository search does not prove every caller or stored representation is found.

Semantic compatibility is more than parseability: a rename, changed unit, new default, altered event meaning, different error, ordering change, or delete behavior can break a contract while types still validate.

Choose a compatible state sequence

Use direct replacement only when every lean condition is evidenced. Otherwise:

  1. Expand: add the new representation or behavior while old producers, consumers, and recovery versions remain valid.
  2. Migrate: copy, backfill, or derive existing state through an idempotent, resumable, observable process that preserves authorization and tenant boundaries.
  3. Switch: move authoritative writers and readers in a deliberate order. Declare one source of truth; if dual writes are unavoidable, define conflict authority, failure handling, reconciliation, and expiry.
  4. Verify: compare constraints, counts, checksums, semantic samples, error behavior, latency, and consumer outcomes against sourced gates.
  5. Contract: remove the old path only after old consumers and rollback versions are gone, reconciliation closes, the recovery decision is updated, and cleanup is authorized.

Keep phases independently deployable. At every boundary state the supported version combinations, who owns advancement, what pauses the migration, and whether rollback or roll-forward is safe. A runtime rename is usually add, copy, switch, remove.

Make movement and failure recoverable

  • Pin source scope, target representation, transformation version, reference data, checkpoints, and expected population.
  • Make backfills idempotent and resumable across concurrent writes, retries, duplicates, partial batches, interruption, and restart.
  • Never let a default turn unconvertible data into plausible but wrong data; quarantine exceptions with safe identifiers, counts, and an owner.
  • Estimate locks, storage, logs, queues, replication, latency, and downstream impact before live movement.
  • Identify the latest safe reversal point and every step that destroys rollback compatibility.

Gate every live transition

Before a production backfill, writer or reader switch, schema enforcement, traffic cutover, old-path disablement, destructive contraction, rollback, roll-forward, or cleanup, complete:

  • Target: environment, contract versions, components, consumers, data population, current authoritative path.
  • Authority: active identity and authorization for this phase, target, and any destructive or public effect.
  • Action: one bounded transition, expected mixed-version state, compatibility and data effects.
  • Stop: consumer, correctness, authorization, performance, scope, observability, or reconciliation conditions that pause or abort.
  • Recovery: rollback or roll-forward state, latest safe reversal point, preserved compatibility, owner.
  • Readback: effective contracts and versions, authoritative reader and writer, reconciliation, consumer behavior, service outcome.

The execution skill (operate-production-safely, change-production-data-safely, or release-production-changes) is primary for the command itself; this gate preserves migration state across them.

Verify reachable states and retire deliberately

Test fresh and upgraded instances, old and new producers and consumers, representative legacy data, partial migration, rerun, interruption and resume, rollback, and roll-forward. Exercise the real migration mechanism in a safe representative environment; generated SQL or a unit test alone proves nothing operational. Before contraction, prove old traffic has ceased through authoritative inventory and observation. Confirm cleanup of compatibility branches, shadow paths, dual writes, staging tables, temporary access, and migration jobs, or leave each with an owner and removal condition.

Stop and ask when

  • an unknown consumer or stored representation may exist and cannot be ruled out;
  • a phase value (window, batch limit, threshold) is unknown;
  • the next phase would destroy rollback compatibility and that irreversibility has not been explicitly accepted.

Done when

The report states the phase sequence, deployment order, supported version matrix, known and unknown consumers, movement and reconciliation evidence, cutover state, rollback boundary, irreversible actions, cleanup status, and unresolved decisions. Never claim completion while an old consumer, data exception, or recovery assumption remains unexplained.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.