| name | refactor-workflow |
| description | Use for delivery-mode tasks whose purpose is structural change with no intended behavior change: extracting, moving, or renaming code, replacing a flawed abstraction, or consolidating duplication. Sequences a behavior lock, the owning structural-change skill, and equivalence evidence. Do not use for behavior-changing feature work, or the in-feature preparatory-refactor step, which stays in dev-workflow step 2b. |
| metadata | {"short-description":"Behavior-preserving refactor lane","resources":["references/refactor-workflow.md"]} |
Purpose
Use this skill as the lane for delivery-mode tasks whose purpose is structural change: the code's externally observable behavior must not change, only its internal shape. It is a thin composition layer over existing parts — it does not own any new mechanism, and it does not replace dev-workflow's gates. dev-workflow routes here by declared intent; this lane hands the task back to dev-workflow/$quality-gate to close.
When to use
Use when the task's declared intent (dev-workflow step 1a) is refactor: extracting/moving/renaming code, replacing a flawed abstraction, consolidating duplication, or improving physical layout, with no intended behavior change.
Do not use for:
- behavior-changing feature work (intent
feature) — any intentional behavior change belongs there, not here.
- the in-feature preparatory-refactor step done to make a feature change easy first — that stays in
dev-workflow step 2b.
How to use
Open references/refactor-workflow.md when following the stage table for this lane.
-
Record intent: refactor and the compat-mode. Compat-mode semantics (preserve / staged / break-allowed) are owned by dev-workflow step 1b — cite the recorded value here, do not restate its definitions.
-
Lock behavior before any structural edit: run the full suite and record it green as the baseline. If tests for the touched area are unreliable, slow, or absent, stop and add characterization tests first via $working-with-legacy-code; size those tests with $unit-test-design's E/S/H tiers (cite the tier, do not restate the risk formula).
-
Make the structural change through the one owning part-skill for its scope — do not improvise a mechanism this skill does not own:
- function/API-level shape →
$function-boundary-governor
- module/class responsibility →
$design-balance
- temporary red-state migration replacing a flawed abstraction →
$destructive-refactor (under refactor intent its intentional-behavior-change allowance is unavailable — behavior preservation stays mandatory, and its "add/update tests" step is limited to keeping migrated call sites green)
- physical file/module layout →
$project-structure
New tests are not written for moved-but-unchanged behavior — the stage-1 lock is the equivalence evidence for that code. $implementation-economy still applies to any new abstraction the refactor introduces.
-
Close with equivalence evidence: pre-existing tests are unchanged and green; test edits are allowed only for renamed/moved symbols, and each such edit is listed by file and symbol; no new public behavior was introduced; under compat-mode break-allowed, the check_api_removal.py sweep (see $destructive-refactor) returns zero hits.
-
Name anti-patterns before calling the task done: a "refactor" that changes behavior is a mislabeled feature change; deleting a failing test to reach green is forbidden; skipping the stage-1 lock because "the change is obviously safe" is forbidden; a big-bang rewrite where $destructive-refactor's staged migration fits is a scope error.
-
Continue into dev-workflow's remaining steps (structure watch, verification, $quality-gate) — this lane supplies evidence for the gate's refactor bullet, it does not substitute for the gate.
Output expectation
- compat-mode:
preserve | staged | break-allowed (cited from dev-workflow step 1b)
- lock evidence: baseline suite command + result, or characterization tests added (cite
$working-with-legacy-code output and the $unit-test-design tier used)
- stage list: which owning part-skill ran for the structural change and its decision
- equivalence evidence: pre-existing tests unchanged-and-green status; no-new-public-behavior statement;
break-allowed sweep result when applicable
- any listed test edits: file + symbol + reason (renamed/moved only)
