Adopt and Delete (no dead code)
When you adopt a shared module, library, chart, or service — or consolidate duplicates — delete the code it supersedes in the same change. The change that introduces the replacement must remove what it replaced. No orphaned, dead, or duplicated code left behind.
The rule
A migration is not "add the new path." It is "add the new path AND remove the old one," as one atomic, reviewable unit. If the old code still compiles and runs after your change, you adopted and forked — you did not adopt-and-delete.
Why (the failure mode this prevents)
Leftover duplicates don't sit quietly — they rot:
- Drift: the old and new copies diverge; bugs fixed in one reappear from the other.
- False-done: "migrated to the shared lib" reads as complete while the inlined copy is still the one actually running.
- The clean footgun: a
git clean / fresh checkout deletes the untracked-or-half-removed remnants and silently changes behavior.
- Ambiguity: the next contributor can't tell which path is canonical, so they edit the wrong one.
Dead code is not free. It is a standing liability that costs every future reader.
How to do it
- Find every caller of the thing you're replacing before you start — that set is your deletion checklist, not an afterthought.
- Switch callers to the new path.
- Delete the superseded code — the old module, the inlined copy, the duplicate chart, the now-unused config — in the same commit/PR.
- Grep for stragglers: references, imports, dead flags, docs pointing at the old path. Zero hits is the done bar.
- One concern per change: if the deletion is large, the adoption and the deletion still ship together — split by area, not into "add now, delete later." "Delete later" is how dead code is born.
Done bar
- The replaced code no longer exists in the tree.
- No reference, import, or doc points at it.
- The build/tests pass because of the new path, not because both still exist.
When to use / not
- Use for migrations, consolidations, shared-module adoption, dedup, refactors that supersede code.
- Not a reason to delete code that is still a live, separate concern — only delete what your change actually replaces. Removing unrelated code is a different change.
Anti-patterns
- "Add the new path now, delete the old one in a follow-up" — the follow-up never lands; the dupe drifts.
- Leaving the old module importable "just in case" / "for backwards-compat" with no caller and no deprecation plan.
- Commenting out the old code instead of deleting it (version control already remembers it).
- Marking a migration done while the old copy is still the one in the running path.
1---2name: adopt-and-delete3description: Use when adopting a shared module, library, chart, or service, or doing any consolidation, migration, or refactor that supersedes existing code. The change that adds the replacement must REMOVE what it replaced, in the same atomic change.4---56# Adopt and Delete (no dead code)78When you adopt a shared module, library, chart, or service — or consolidate duplicates — **delete the code it supersedes in the same change.** The change that introduces the replacement must remove what it replaced. No orphaned, dead, or duplicated code left behind.910## The rule11A migration is not "add the new path." It is **"add the new path AND remove the old one,"** as one atomic, reviewable unit. If the old code still compiles and runs after your change, you adopted *and forked* — you did not adopt-and-delete.1213## Why (the failure mode this prevents)14Leftover duplicates don't sit quietly — they rot:15- **Drift**: the old and new copies diverge; bugs fixed in one reappear from the other.16- **False-done**: "migrated to the shared lib" reads as complete while the inlined copy is still the one actually running.17- **The clean footgun**: a `git clean` / fresh checkout deletes the untracked-or-half-removed remnants and silently changes behavior.18- **Ambiguity**: the next contributor can't tell which path is canonical, so they edit the wrong one.1920Dead code is not free. It is a standing liability that costs every future reader.2122## How to do it231. **Find every caller** of the thing you're replacing before you start — that set is your deletion checklist, not an afterthought.242. **Switch callers to the new path.**253. **Delete the superseded code** — the old module, the inlined copy, the duplicate chart, the now-unused config — in the same commit/PR.264. **Grep for stragglers**: references, imports, dead flags, docs pointing at the old path. Zero hits is the done bar.275. **One concern per change**: if the deletion is large, the adoption and the deletion still ship together — split by *area*, not into "add now, delete later." "Delete later" is how dead code is born.2829## Done bar30- The replaced code no longer exists in the tree.31- No reference, import, or doc points at it.32- The build/tests pass *because* of the new path, not because both still exist.3334## When to use / not35- **Use** for migrations, consolidations, shared-module adoption, dedup, refactors that supersede code.36- **Not** a reason to delete code that is still a live, separate concern — only delete what your change actually replaces. Removing unrelated code is a different change.3738## Anti-patterns39- "Add the new path now, delete the old one in a follow-up" — the follow-up never lands; the dupe drifts.40- Leaving the old module importable "just in case" / "for backwards-compat" with no caller and no deprecation plan.41- Commenting out the old code instead of deleting it (version control already remembers it).42- Marking a migration done while the old copy is still the one in the running path.
selamy-labs