deprecate

name

deprecate

description

Use when something has to be removed or retired — a feature, endpoint, table column, config key, feature flag, package or whole service; migrating consumers off an old API or version; code that looks dead but might not be. Symptoms: "can we delete this?", "is anything still using this?", "we need everyone off v1", "kill the old one". Not for restructuring that keeps the interface — that's the `refactorer` agent.

MasterMind — Deprecate

Every other skill adds or fixes. This one deletes, migrates and retires — the half of engineering where the reward (a smaller system) arrives long after the risk, and where what breaks is whatever you couldn't see was still reading it.

The shape: expand → migrate → contract

Any removal that can't land in one atomic commit takes three phases, in this order, each shipped on its own:

• Expand — add the new thing beside the old. Both work. Nothing has moved yet, and stopping here breaks nothing.
• Migrate — move consumers in batches sized by blast radius: one caller at a time where a mistake pages someone, a whole service where it doesn't. Verify each batch before starting the next.
• Contract — remove the old, once nothing reads it.

Renaming users.email_addr to users.email on a live system, as five deploys:

1  add `email` · backfill · write both · still read `email_addr`   ← expand, fully reversible
2  read `email` · keep writing both                                ← the only behavior change; watch it
3  move every caller off `email_addr`, batch by service            ← migrate
4  stop writing `email_addr` · leave the column for one rollback window
5  drop the column                                                 ← contract

Each line deploys and reverts on its own; the sequence is the safety. Collapse any two and you get the classic outage — during a rolling deploy both versions run at once, so the instance that hasn't restarted yet is still writing to the column you just dropped.

Prove it's unused — never assert it

Never contract on a search you didn't run, and never treat one symbol search as the answer. "Nothing references it" is a claim about the whole system, and the places that break are the ones a symbol search can't see: config and environment, infra and CI, docs, runbooks and dashboards, other repos and clients you don't build, and every dynamic reference — a name assembled from a string, reflection, a container registration, a route table, a serialized payload, a stored default, an analytics event name. Search for the spelling, everywhere it could be written, not the identifier inside one tree.

The excuses to catch in yourself: "it's obviously dead" — obvious to you, not to the caller in someone else's repo · "the search came back empty" — empty for that spelling, in that tree · "we can always put it back" — not for data, and not for whoever broke in between.

When you can't prove it from the outside, measure it from the inside. Ship a counter or a log line on the old path, wait a real interval — one full business cycle, including the monthly job and the quarterly report — then delete against recorded evidence instead of against absence of evidence.

Advisory or compulsory — pick one out loud

A deprecation with no removal date is advisory, and advisory deprecations get ignored, correctly: nothing happens to anyone who skips them. A date makes it compulsory — and the date is a promise you now owe. Choose, and say which:

• No date → say plainly that it's a preference, and budget to maintain both paths indefinitely.
• A date → name it, name who moves each consumer, and hold it. A removal date that slips twice teaches everyone the next one is fiction.

The churn rule

If you own the thing being deprecated, you own migrating its users. A deprecation notice doesn't remove the work — it multiplies it by the number of teams and bills them for a decision they didn't make. Where you can reach the code, do the migration. Where you can't, ship the codemod, the adapter or the script: a tool, not an announcement.

Zombie code — no owner, live consumers

The state worth naming, because most rot lives in it: code nobody maintains that something still calls. It isn't dead (the traffic proves it) and it isn't alive (nobody will change it), and limbo protects it — nobody dares delete it, nobody dares touch it, and every incident inside it opens with an archaeology dig.

A zombie gets an owner or a removal date. There is no third state. Write down which one it got.

Deleting is a verified change like any other

The check proving nothing broke is the work — ~/.mastermind/engineering/core/rigor.md governs the verification, the evidence-backed report, and the "say first, then do" tier that already covers data migrations and deleting files that aren't yours. Two things belong to removal specifically:

• Keep the deletion its own commit. Bundled with a refactor, the revert stops being one action.
• The old path is the rollback path. Contract after the rollback window closes, not before.

Gotchas

• Data outlives code. Rows the old path wrote, queued jobs carrying the old shape, cached payloads, a mobile build from eight versions ago nobody can force-update. Consumers with no call site to find.
• Removing a flag is a deprecation. Delete the losing branch and the flag together; a flag deleted on its own leaves a branch nothing can reach and nobody will read.
• Non-code consumers break too. A metric name in a dashboard, an alert query, a runbook step, a documented example people copy-paste.
• Deleting a feature's tests is right; deleting the coverage isn't. If a test reached shared behavior through the deleted path, that behavior is now untested — move the test rather than dropping it.