deprecation-migrationlisted

# Deprecation and Migration Code is a liability, not an asset. Every line carries maintenance cost — bugs, dependency updates, security patches, onboarding overhead. Deprecation is the discipline of removing code that no longer earns its keep; migration is the process of moving users safely from old to new. Most organizations build things well; few remove them well. Hyrum's Law makes removal hard: with enough users, every observable behavior becomes depended on — including bugs, timing quirks, and undocumented side effects. Deprecation therefore requires active migration, not just announcement. Plan removal at design time — systems with clean interfaces, feature flags, and minimal surface area are far easier to sunset. ## When to use - Replacing an old system, API, or library with a new one. - Sunsetting a feature that's no longer needed, or consolidating duplicate implementations. - Removing dead code that nobody owns but everybody depends on. - Planning the lifecycle of a new system (deprecation planning starts at design time). - Deciding whether to maintain a legacy system or invest in migration. - Upgrading a dependency or framework version, including major/breaking upgrades (see `references/dependency-upgrade.md`). - Moving data between systems (dual-write, backfill, CDC, cutover) — see `references/data-migration.md`. **Not for:** patching a security vulnerability in place (use `security-review`); routine commits (use `git-workflow`). ## Steps ### 1. Make the depr