Deprecate Legacy Systems and Migrate Users Safely

This skill treats code as a liability rather than an asset, since every line has ongoing maintenance cost from bugs, dependencies, security patches, and onboarding overhead, and provides a discipline for deprecating code that no longer earns its keep and migrating users safely from old to new. Its core principles hold that code's value lies in the functionality it provides, not the code itself; that Hyrum's Law makes removal hard, since with enough users every observable behavior, including bugs and undocumented side effects, becomes depended on, which is why deprecation requires active migration rather than just an announcement; and that deprecation planning should start at design time by asking how a system would be removed in three years, so it's built with clean interfaces, feature flags, and minimal surface area from the start. Before deprecating anything, five questions must be answered: does the system still provide unique value, in which case it should be maintained; how many consumers depend on it, quantifying the migration scope; does a replacement exist, since a system should never be deprecated without one; what's the per-consumer migration cost, automating it if trivial and weighing it against maintenance cost if manual; and what's the ongoing cost of not deprecating it, covering security risk, engineer time, and complexity. Deprecation is either advisory, meaning optional migration on the user's own timeline via warnings and documentation and the default choice, or compulsory, meaning a hard removal deadline used only when maintenance cost or risk justifies forcing migration, and always accompanied by migration tooling, documentation, and support rather than a bare announcement.

The migration process runs four steps: build the working replacement first, covering all critical use cases, documented, and production-proven rather than just theoretically better; announce and document through a deprecation notice covering status, replacement, removal date if any, and reason, plus a concrete migration guide; migrate consumers incrementally one at a time, identifying touchpoints, updating to the replacement, verifying behavior matches, removing old references, and confirming no regressions, governed by a rule that whoever owns the deprecated infrastructure is responsible for migrating its users or shipping backward-compatible updates requiring no migration, not leaving users to figure it out; and only remove the old system after verifying zero active usage through metrics, logs, or dependency analysis, then deleting the code, tests, documentation, configuration, and deprecation notices together. Three migration patterns are documented: the strangler pattern, running old and new systems in parallel while incrementally routing traffic from the old to the new before removing the old system; the adapter pattern, a class implementing the old interface that delegates to the new implementation so consumers keep their existing calls during a backend migration; and feature-flag migration, switching individual consumers between old and new service implementations per flag. It defines zombie code as unowned but depended-upon code with no recent commits, no assigned maintainer, unfixed failing tests, or vulnerable unmaintained dependencies, which must either get an assigned owner and real maintenance or a concrete deprecation plan, since it cannot stay in limbo. A rationalizations table rebuts common excuses for not removing code, such as it still works, someone might need it later, migration is too expensive, or users will migrate on their own.

Use it when replacing an old system, API, or library, sunsetting an unneeded feature, consolidating duplicate implementations, removing unowned dead code, planning a new system's lifecycle from the start, or deciding whether to maintain a legacy system versus invest in migrating off it.

Given a system to deprecate, it produces a deprecation decision, an advisory or compulsory plan, a deprecation notice with a migration guide, an incremental migration process per consumer, and a verified, fully removed old system.

No specific tooling is mandated; it pairs with feature-flag systems for gradual cutover and standard metrics and logging for verifying zero active usage before removal.

Engineering teams and AI-agent workflows managing the lifecycle of systems, APIs, or libraries who need a disciplined process for safely removing code rather than letting deprecated or zombie systems accumulate indefinitely.