---
name: principle-converge-on-the-target
description: "Apply during planned rewrites, migrations, and API replacements. Optimize for the intended end state instead of preserving smooth intermediate states; migrate callers and delete the old path in the same wave. Expand-and-contract only at deployed boundaries you cannot migrate atomically."
disable-model-invocation: true
---

# Converge on the Target

Optimize for the intended, verifiable end state rather than preserving smooth intermediate states. Compatibility code kept only to make a transition comfortable becomes long-lived debt.

**Core rule:**

- Prioritize end-state integrity over transitional stability.
- Intermediate breakage is acceptable when it is planned, scoped, and reversible. Declare where breakage is acceptable before starting.
- Verifiable is not the same as stable. Breakage tolerance never exempts a unit from its check: each unit of the migration still ends in a state you can check (the **sequence-verifiable-units** principle skill), but the system need not stay fully working between phases via throwaway shims.
- Keep high-signal checks for actively touched areas while migrating, and run full static and runtime verification at plan completion.

**The internal-API instance.** When a new internal API is the right design, migrate callers and remove the old API in the same refactor wave:

- Do not keep legacy API paths alive only because internal callers still exist.
- Inventory callers, migrate them, and delete the old API immediately.
- Treat temporary adapters as exceptional and time-boxed, not default architecture.
- Update tests to assert the new contract, and delete tests that only protect pre-refactor implementation details.

Keeping both old and new APIs creates dual-path complexity, slows cleanup, and makes the codebase feel append-only.

**Scope: the boundary decides the discipline.** Same-wave deletion applies where you control every caller: internal APIs, one repo, coordinated breaking changes the project can absorb. A deployed boundary you cannot migrate atomically (a published API, a database other releases read, an event schema with external consumers) takes the opposite discipline: expand and contract, dual-read or dual-write transition periods, versioned schemas. Both are this principle. Applying same-wave deletion to a deployed boundary breaks consumers you do not control; applying expand-and-contract to an internal API leaves compatibility layers nobody needed.