deprecate-and-migrate

# Deprecation and Migration ## Overview Deprecation removes code that no longer earns its cost. Migration moves consumers from the old path to the new one without breaking them. Building is the easy half. Removal is the half most teams skip. This skill covers removal. ## When to Use - Replacing an old system, API, or library with a new one - Sunsetting a feature that's no longer needed - 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 ## Core Principles ### Code Is a Liability Every line costs maintenance: tests, docs, security patches, dependency updates, and cognitive load on nearby work. Functionality is what users buy; the code is what you pay. When the same functionality fits in less code, less state, or a cleaner interface, retire the old code. ### Hyrum's Law Makes Removal Hard Past a certain consumer count, every observable behavior gets depended on, including bugs, timing quirks, and undocumented side effects. Deprecation therefore needs active migration rather than just an announcement. A consumer cannot "just switch" while it relies on behavior the replacement does not reproduce. ### Deprecation Planning Starts at Design Time When building something new, ask how it gets removed in three years. Clean interfaces, feature flags, and a small surface ...