Compass Method Refactoring

Before moving anything, name what must still be true afterwards and find what checks it. A refactor without that is indistinguishable from a rewrite with optimism.

Where nothing checks it, the first unit of work is the check, not the move. That check is also the deliverable's proof, so it is never wasted.

Resolve the concepts (Grounding), then find everything that references what you are about to change, including archived documents and generated output. The cost of a refactor is dominated by the references nobody remembered, and finding them is mechanical.

Ask what can be deleted outright before deciding where the rest should live (principle-subtract-before-you-add). Code that no longer needs to exist is the cheapest thing to move, because it does not get moved.

Ask also whether the shape is right rather than merely tidier (principle-redesign-from-first-principles). A refactor that preserves a structure nobody would choose today has spent effort to keep a decision that should have been revisited.

A change across many files is a script, not an afternoon (principle-build-the-lever). The script is what a reviewer re-runs, it is idempotent so a partial run is recoverable, and it is what makes the next change of the same shape cheap.

Give it a --check mode where the new state is something that could drift back, and wire that into CI (principle-encode-lessons-in-structure). A refactor whose result nothing enforces is a shape that decays.

Sequence the change so each step ends in a system that builds and passes (principle-sequence-verifiable-units). Where an old and a new form must coexist, migrate the callers and delete the old one in the same wave rather than leaving both: two ways to do one thing is the debt the refactor was meant to remove (principle-migrate-callers-then-delete-legacy-apis).

Run the invariant from phase 1 (principle-prove-it-works), then the class checks for what you touched via compass-code-run-build. For generated code, the proof is byte-identical regeneration (compass-codegen-fix-drift).

A green build is necessary and not sufficient: it says nothing about the references that live in documentation, and those break silently.

Close with compass-agile-close-task and raise with compass-pr-raise. Keep the script in the tree: it is the artefact that makes the change reviewable and repeatable.