deprecate-and-remove

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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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 cannot run safely in a delivery worktree (the dependency-upgrade skill). A half-removed feature leaves a reader guessing which half is real.
6. 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.
7. 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.
8. 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.