Deprecate, then remove
Removing code changes a contract somebody may still hold. Find every dependent, warn
before you cut, remove in the right order, and prove nothing still points at the thing
you deleted. Dead code that is really dead is the best diff there is; dead code that is
secretly load-bearing is an incident.
Steps
- Prove it is dead — and write the proof down. Search for every reference,
including the non-obvious ones:
- the symbol and its string form (
grep -rn): reflection, dynamic imports, DI
registration, templates, routes tables, serialised names, cron/job registries;
- tests, fixtures, docs, scripts, CI workflows, dashboards and infra config;
- for a flag or option: every read, and every place that sets it;
- for a column or table: every query, ORM model, migration and report;
- other repos:
find_dependents and search_lore for declared consumers, and grep any
read-only context repos listed in your prompt.
"No callers" is a claim; the commands you ran and their empty output are the evidence.
- Decide: deprecate first, or remove now. Anything with consumers you cannot see —
another repo, a public or partner API, an operator-set option, a persisted format —
gets a deprecation period. Purely internal code with an empty step-1 search is removed
now. Semantic versioning puts a deprecation in a minor release and the removal in the
next major. If you cannot tell which case applies,
request_decision.
- When deprecating, make it loud and dated. Mark it deprecated where tooling shows it
(JSDoc
@deprecated, warnings.warn(DeprecationWarning), [Obsolete], #[deprecated]),
log a warning on use (once, not per call), document the replacement, and set the
removal date. For HTTP APIs send Deprecation (RFC 9745) and Sunset (RFC 8594)
headers with a Link to the migration note; the sunset date must not precede the
deprecation date.
- Remove in dependency order. Callers before callees; public surface before
implementation; code before schema. Data follows expand/contract (the
add-db-migration skill): stop writing, then stop reading, then drop — in separate
deliveries when the repo deploys them separately.
- Delete completely. Code, tests, fixtures, types, docs, config keys, flag
declarations, and now-unused helpers that only the dead code used. A dependency that
becomes unused is listed in your evidence for a human to remove: package-manager
commands are hook-blocked in a delivery worktree, so give the exact removal command.
A half-removed feature leaves a reader guessing which half is real.
- Fail loudly for stragglers. An old API caller gets an explicit error with a
pointer (HTTP 410 Gone with a link, a CLI message naming the replacement), not a silent
404 or a no-op stub that swallows the call.
- Verify nothing else moved. Run the full suite, build and lint once: removals break
through import side effects, registration order, and shared helpers. Re-run the
step-1 search to show zero remaining references.
- Record it. A CHANGELOG "Removed"/"Deprecated" entry in the repo's format (the
changelog-generator skill), and evidence via the record-evidence skill: the
searches and their empty results, what was deprecated-not-removed and its removal date.
On a resume that call is refused: do not retry; put this, the AC → test map and the
smallest-change note in your final message.
Done when
The post-removal search returns nothing (or only the deliberate deprecation shim), the
full suite and build pass, stragglers get an explicit error, and the evidence contains
the search commands and results.
Stop and escalate when
- A dependent turns up that the ticket did not anticipate (another repo, a scheduled job,
an operator runbook): stop removing and
request_decision with what you found.
- The removal would drop or rewrite persisted data, or needs usage data (request logs,
metrics) you cannot access to prove the thing is unused:
request_decision
(human_required) with the search results you have.
Rules
- No removal without a dependent search whose result is in the evidence.
- External consumers get a dated deprecation and a documented replacement first.
- Remove in dependency order; data removals follow the migration phases.
- Remove the whole thing; never leave a stub that silently swallows old calls.
- Work on the delivery branch (verify with
git branch --show-current); commit, never push.
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While hunting dependents you learn who still relied on the thing and why it existed — a boundary or decision that was never written down. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
1---2name: deprecate-and-remove3description: Use when a ticket retires something — a feature flag, an endpoint, a config option, a module, a column, a CLI command — and the removal must not break callers, data, or operators who still depend on it. Invoke for "remove the legacy X", "delete dead code", "drop the old API", or "clean up after the migration".4stack: []5area: workflow6metadata:7 source: https://skillmd.com/skills/tmj-90/deprecate-and-remove8---910# Deprecate, then remove1112Removing code changes a contract somebody may still hold. Find every dependent, warn13before you cut, remove in the right order, and prove nothing still points at the thing14you deleted. Dead code that is really dead is the best diff there is; dead code that is15secretly load-bearing is an incident.1617## Steps18191. **Prove it is dead — and write the proof down.** Search for every reference,20 including the non-obvious ones:21 - the symbol and its string form (`grep -rn`): reflection, dynamic imports, DI22 registration, templates, routes tables, serialised names, cron/job registries;23 - tests, fixtures, docs, scripts, CI workflows, dashboards and infra config;24 - for a flag or option: every read, and every place that sets it;25 - for a column or table: every query, ORM model, migration and report;26 - other repos: `find_dependents` and `search_lore` for declared consumers, and grep any27 read-only context repos listed in your prompt.28 "No callers" is a claim; the commands you ran and their empty output are the evidence.292. **Decide: deprecate first, or remove now.** Anything with consumers you cannot see —30 another repo, a public or partner API, an operator-set option, a persisted format —31 gets a deprecation period. Purely internal code with an empty step-1 search is removed32 now. Semantic versioning puts a deprecation in a minor release and the removal in the33 next major. If you cannot tell which case applies, `request_decision`.343. **When deprecating, make it loud and dated.** Mark it deprecated where tooling shows it35 (JSDoc `@deprecated`, `warnings.warn(DeprecationWarning)`, `[Obsolete]`, `#[deprecated]`),36 log a warning on use (once, not per call), document the replacement, and set the37 removal date. For HTTP APIs send `Deprecation` (RFC 9745) and `Sunset` (RFC 8594)38 headers with a `Link` to the migration note; the sunset date must not precede the39 deprecation date.404. **Remove in dependency order.** Callers before callees; public surface before41 implementation; code before schema. Data follows expand/contract (the42 `add-db-migration` skill): stop writing, then stop reading, then drop — in separate43 deliveries when the repo deploys them separately.445. **Delete completely.** Code, tests, fixtures, types, docs, config keys, flag45 declarations, and now-unused helpers that only the dead code used. A dependency that46 becomes unused is listed in your evidence for a human to remove: package-manager47 commands are hook-blocked in a delivery worktree, so give the exact removal command.48 A half-removed feature leaves a reader guessing which half is real.496. **Fail loudly for stragglers.** An old API caller gets an explicit error with a50 pointer (HTTP 410 Gone with a link, a CLI message naming the replacement), not a silent51 404 or a no-op stub that swallows the call.527. **Verify nothing else moved.** Run the full suite, build and lint once: removals break53 through import side effects, registration order, and shared helpers. Re-run the54 step-1 search to show zero remaining references.558. **Record it.** A CHANGELOG "Removed"/"Deprecated" entry in the repo's format (the56 `changelog-generator` skill), and evidence via the `record-evidence` skill: the57 searches and their empty results, what was deprecated-not-removed and its removal date.58 On a resume that call is refused: do not retry; put this, the AC → test map and the59 smallest-change note in your final message.6061## Done when6263The post-removal search returns nothing (or only the deliberate deprecation shim), the64full suite and build pass, stragglers get an explicit error, and the evidence contains65the search commands and results.6667## Stop and escalate when6869- A dependent turns up that the ticket did not anticipate (another repo, a scheduled job,70 an operator runbook): stop removing and `request_decision` with what you found.71- The removal would drop or rewrite persisted data, or needs usage data (request logs,72 metrics) you cannot access to prove the thing is unused: `request_decision`73 (`human_required`) with the search results you have.7475## Rules7677- No removal without a dependent search whose result is in the evidence.78- External consumers get a dated deprecation and a documented replacement first.79- Remove in dependency order; data removals follow the migration phases.80- Remove the whole thing; never leave a stub that silently swallows old calls.81- Work on the delivery branch (verify with `git branch --show-current`); commit, never push.8283## Capture lore8485This skill is one of the places durable, reusable knowledge naturally surfaces:86**While hunting dependents you learn who still relied on the thing and why it existed — a boundary or decision that was never written down.** That kind of fact is *lore*. Capture it via the **lore-capture87protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):88call the Memory MCP `suggest_lore` once at the close of your work — reusable89conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.