deprecation-and-migration

1# Deprecation and Migration
2 
3## Overview
4 
5Code is a liability, not an asset. Every line of code has ongoing maintenance cost — bugs to fix, dependencies to update, security patches to apply, and new engineers to onboard. Deprecation is the discipline of removing code that no longer earns its keep, and migration is the process of moving users safely from the old to the new.
6 
7Most engineering organizations are good at building things. Few are good at removing them. This skill addresses that gap.
8 
9## When to Use
10 
11- Replacing an old system, API, or library with a new one
12- Sunsetting a feature that's no longer needed
13- Consolidating duplicate implementations
14- Removing dead code that nobody owns but everybody depends on
15- Planning the lifecycle of a new system (deprecation planning starts at design time)
16- Deciding whether to maintain a legacy system or invest in migration
17 
18## Core Principles
19 
20### Code Is a Liability
21 
22Every line of code has ongoing cost: it needs tests, documentation, security patches, dependency updates, and mental overhead for anyone working nearby. The value of code is the functionality it provides, not the code itself. When the same functionality can be provided with less code, less complexity, or better abstractions — the old code should go.
23 
24### Hyrum's Law Makes Removal Hard
25…