deprecation-and-migration

To safely deprecate a legacy API, apply a 5-question decision matrix evaluating value, consumer impact, replacement readiness, migration cost, and maintenance risk, then use adapter or feature-flag patterns to migrate consumers before final removal.

The best way to kill zombie code is to treat it as a deprecation candidate by evaluating it through a decision matrix, documenting spec deltas, and verifying usage reaches zero before compulsory removal to prevent long-term maintenance risks.

Strangler and adapter patterns work for software migration by incrementally routing traffic from legacy systems to verified alternatives, reducing risk and enabling rollback while you replace production behaviors without massive consumer breakage.

Advisory deprecation relies on warnings and documentation when immediate migration is flexible, while compulsory deprecation enforces migration with tooling and outreach when ongoing maintenance risk or replacement readiness demands strict removal timelines.

Yes, this deprecation workflow requires explicit OpenSpec spec delta documentation to tie deprecation proposals to verification steps and cleanup, ensuring the repository never promises capabilities that have already been removed.

Feature flags reduce risk and enable rollback during migration, but they require strict cohort management and eventual cleanup; if usage is not verified at zero before final flag removal, you risk retaining zombie code and ongoing maintenance overhead.