Breaking Refactors — Freedom Through Structure

Compatibility layers are coupling debt with interest. Every compat shim is a decision deferred, not a decision avoided. Break cleanly, break once, break with evidence.

Principles

1. No half-measures. A partial migration is worse than no migration — it doubles the surface area and confuses every reader.
2. One migration direction. Old-to-new only. Never add new-to-old adapters; that entrenches the old path.
3. Blast radius awareness. Map every consumer before removing anything. Surprise breakage is a planning failure, not a courage signal.
4. Dead code is a lie. "Just in case" code is not dead — it actively misleads readers about what the system does.
5. Compat shims are temporary. If a shim has no removal date, it is permanent. If it is permanent, it is architecture. Decide which.

Reconnaissance Checklist

Before breaking anything, find and catalog: