A strict protocol to complete migrations, eliminate legacy duality, and mechanically enforce the new standard.
Why This Skill Is Needed & Target State
Why this skill is needed: When a new library or tool is introduced without full integration, the legacy pattern remains operational. Engineers and agents default to familiar legacy habits or copy nearby outdated code. Relying on human vigilance or review comments to enforce adoption is ineffective: rules maintained solely by goodwill do not exist in practice. As a result, old and new implementations coexist indefinitely, confusing readers and doubling maintenance overhead.
Target state: Only the new standard is used across the codebase, and the legacy approach cannot be used even accidentally because mechanical guardrails (linters, type boundaries, or removal) forbid it.
Invariant Rules
- Migrate All Existing Callers in the Same Wave: Migrate all existing occurrences to the new standard per
migrate-callers-then-delete-legacy-apis. Never leave partial migrations for a future speculative phase. - Mechanically Enforce the Boundary: Prevent new code from using the deprecated method using structural gates (lint rules like
no-restricted-imports, compiler type constraints, or CI checks), never through documentation warnings alone perencode-lessons-in-structure. - Standardize on One Canonical Pattern: Converge on exactly one way to invoke the new tool so readers do not seek phantom significance in syntax variations.
- Delete Deprecated Implementations & Dependencies: Completely excise obsolete functions, dead shims, and unused dependencies from manifests and lockfiles per
subtract-before-you-add.
Execution Workflows
integrate-new-tool: Step-by-step workflow for adopting a dependency, migrating call sites, and locking the gate.
Domain References
mechanical-enforcement: Linters, compiler barriers, and CI assertions that lock out deprecated patterns.
Delegated Skills
poteto-principles: Followmigrate-callers-then-delete-legacy-apis,encode-lessons-in-structure, andsubtract-before-you-add.dont-it-yourself: Confirm that the incoming tool replaces custom home-rolled code.