---
name: loom-deprecation-and-migration
description: "Use when the work is a safe removal or replacement path: deprecating APIs/features, migrating users/data/config/integrations, consolidating duplicate implementations, proving zero usage, or retiring legacy behavior."
---

# loom-deprecation-and-migration

Deprecation and migration is a multi-surface playbook for safe removal and
replacement.

It decides whether change is warranted, specifies the target contract, plans the
migration, executes bounded slices, proves adoption, audits risk, and cleans up.

## Core Dependency

Use `loom-core` first. This playbook composes `loom-research`, `loom-specs`,
`loom-plans`, `loom-tickets`, `loom-evidence`, `loom-audit`, `loom-constitution`,
`loom-knowledge`, and `loom-retrospective`.

## Use This Playbook When

Use this playbook when:

- replacing a system, API, library, data model, workflow, or feature
- sunsetting a feature or old path
- consolidating duplicate implementations
- removing dead or zombie code
- migrating users, data, integrations, records, or configuration
- deciding whether to maintain legacy behavior or invest in migration

## Route

Use this route:

```text
decide -> specify -> plan -> migrate -> prove -> remove -> prevent
```

## Decide

Start with research when the decision is not obvious.

Answer:

- what unique value the old system still provides
- current consumers and usage
- replacement readiness
- migration cost for each consumer
- ongoing maintenance cost and risk
- compatibility obligations
- security, policy, or user impact
- whether removal is advisory or compulsory

Route durable policy, precedent, or risk tolerance to `loom-constitution`.

## Specify

Use `loom-specs` for replacement behavior and compatibility expectations.

Specify:

- old contract and replacement contract
- supported use cases
- behavior intentionally not preserved
- migration scenarios
- data integrity invariants
- deprecation warnings or notices
- removal criteria
- rollback or compatibility story

## Plan

Use `loom-plans` when migration spans multiple tickets.

Useful slices:

- build replacement behind a flag or adapter
- add compatibility layer
- migrate one representative consumer
- migrate remaining consumers by group
- prove zero usage
- remove old code
- remove docs, tests, flags, and config
- update knowledge and prevention records

Plan parallelism carefully. Migrations that share data, schema, generated files,
or public contracts are usually sequential.

## Migrate

Use tickets and Ralph packets for bounded execution.

Common patterns:

- strangler: route traffic gradually from old to new
- adapter: preserve old interface while swapping implementation
- feature flag: switch consumers one group at a time
- codemod: automate broad mechanical updates, then audit sampled output
- dual-write or read-repair only when data consistency needs it and risk is clear

Keep old and new behavior observable during transition.

## Prove

Use evidence for:

- current usage counts
- consumer inventory
- migration verification commands
- tests proving old and new behavior match where required
- rollout metrics
- zero-traffic or zero-reference proof
- deletion search results
- rollback test or dry run

Record what proof does not show, especially for dynamic usage and external
consumers.

## Remove

Remove old code only after removal criteria are satisfied.

Cleanup may include:

- source code
- tests
- docs
- feature flags
- configs
- dashboards or alerts
- deprecation notices
- compatibility shims
- generated artifacts
- knowledge that now points at stale paths

Use `loom-audit` before removal when consumers, data, security, or production
behavior could be missed.

## Prevent

Use `loom-retrospective` to preserve:

- migration procedure
- consumer inventory pattern
- rejected migration approach
- deprecation policy
- cleanup trap
- atlas or knowledge update

## Done Means

The deprecation or migration pass is done when:

- old and replacement contracts are explicit
- migration plan is sliced and sequenced
- consumers and usage were inspected
- evidence supports migration and removal claims
- old paths are removed or intentionally retained with rationale in the consuming
  record
- audit covers material migration/removal risk
- reusable lessons are promoted through retrospective