Refactor Workflow
Change structure; preserve behavior exactly. The existing behavior is the
spec — but it is unknown until proven, because you believe it does X without
having pinned it. So the parse is a characterization test net, captured
GREEN before any edit. Refactoring without it is editing on unparsed input.
The loop (the feature-workflow spine, refactor instance)
- STEP 0 already classified this as a refactor. Scaffold the manifest:
change_new.py --kind refactor --name "...". - Parse the unknown (STAGE 0.5 equivalent): capture characterization tests
that pin the current observable behavior and run them GREEN. If you cannot
make them green first, you do not yet understand the behavior you are about to
preserve — stop. (See
references/characterize.md.) - Gate:
change_check.py --kind refactor <manifest>— blocks until the net is declared. - Change under the net, one behavior-preserving move at a time. A boundary
move → use
boundary-disciplineREFACTOR mode. - Verify obligation: the same net is GREEN after, behavior identical, no new
behavior added.
verify.pygates ship. - Record/ratchet: a refactor that paid down real coupling is shelf signal;
a near-regression the net caught is a
knowledge-ratchetobservation.
The one law here
A refactor changes exactly one thing — structure — and holds behavior invariant. If behavior must change too, it is not a refactor: split it into a refactor (under the net) plus a feature or fix (its own loop).
Files
references/characterize.md— how to capture a behavior-pinning net cheaply.