refactor-safely

name	refactor-safely
description	Restructure existing code safely without changing externally observable behavior. Composes context, design, architecture, code quality, and testing guardrails into a characterization-first refactoring workflow. Use when the user says 'refactor this', 'clean this up', 'untangle this module', 'move this to the right layer', 'simplify this code', or 'improve this structure'.

Refactor Safely

Required Skills

Load these skills based on refactor scope (see Steps 3, 5, 6 for conditional use):

1. framework:knowledge-priming -- Load project context so the refactor grounds in the real codebase. (always)
2. framework:context-anchoring -- Find and load the feature's context doc; capture approved plans and decisions in it. (always)
3. framework:learning-harvest -- Load prior operational learnings at session start; harvest new ones at session end. (always)
4. framework:collaborative-judgment -- Surface trade-offs in structure, seams, and migration sequence instead of silently assuming. (always)
5. framework:clean-code -- Readability, responsibility boundaries, local craft. (always)
6. framework:test-quality -- Characterization tests and the safety net. (always)
7. framework:design-first -- Target-structure planning for significant structural changes. (conditional: Step 3)
8. framework:architecture -- Layer placement and dependency direction. (conditional: responsibilities move across layers in Steps 5/6)
9. framework:domain-driven-design -- Aggregate boundaries and domain behavior. (conditional: domain rules move or sharpen in Step 6)
10. framework:secure-coding -- Trust bounds, authorization, sensitive data handling. (conditional: security-sensitive code touched in Step 6)

Workflow

Step 1: Establish Refactor Context

Start from the current pain, not from a preferred abstraction.

• Identify the target area: a module, service, aggregate, endpoint path, or subsystem.
• Clarify why the refactor is needed: mixed responsibilities, duplication, wrong-layer logic, coupling, poor testability, or unreadable control flow.
• Clarify what the user expects to improve: simpler structure, correct layer placement, smaller units, clearer domain behavior, easier testing, or safer extension points.
• Run framework:learning-harvest Load behavior. Focus hint: "refactoring session — focus: structural health, quality signals".
• Run framework:context-anchoring Document Discovery to check for an existing context doc covering the affected feature/module:
  • Found → Load behavior. Honor every logged decision and constraint as an active commitment while planning the refactor. The doc already contains an approved refactor plan (preservation boundaries + target structure) → confirm it still matches the user's intent, then resume at Step 4 unless the user wants to revisit the plan first.
  • Not found → Proceed from the conversation and the current code. Do not block planning on a missing context doc.

End the step by summarizing the intent in one sentence:

"Refactor X to improve Y while preserving Z."

STOP: If you cannot state both the improvement target and the preservation target that clearly, continue clarifying with the user before planning any changes.

Persistence check:

• Refactor is substantial, risky, or likely to span multiple sessions → ask whether the user wants to persist an approved plan.
• A relevant context doc already exists and the user wants persistence → use it and update it.
• No relevant doc exists and the user wants persistence → propose creating one; confirm the doc name per framework:context-anchoring, then use it as the source of truth for the approved plan.
• The user declines persistence, or the refactor is small and local → continue in non-persistent mode. Approval gates still apply; the plan simply stays in-session.

Step 2: Define Preservation Boundaries

Refactoring changes structure, not behavior. Make the preservation contract explicit before proposing any structural edits.

List the behaviors that must remain unchanged:

• Public API contracts and response shapes
• Domain invariants and state transitions
• Persistence semantics and side effects
• Event emission and integration behavior
• Authorization and security posture
• Error behavior wherever externally visible
• Performance or operational characteristics, if part of the current contract

Also list explicit out-of-scope changes:

• New features
• Schema changes
• Contract changes
• Intentional behavior changes
• Unrelated cleanup outside the approved area

If the desired outcome requires changing preserved behavior, stop and discuss what the task actually is — a bug fix (/bug-fix), a feature change (/design-blueprint), or a broader redesign. STOP: Never proceed as a refactor after making one of those determinations.

Step 3: Propose High-Level Structural Plan

Zero Refactor Rule: make no structural code changes until the user approves both the target structure and the transition plan.

For small refactors the plan may be brief. For larger ones, use framework:design-first selectively:

• Start at Level 2 (Components) to define target responsibilities and boundaries.
• Use Level 3 (Interactions) when data flow or dependency direction will change.
• Use Level 4 (Contracts) when internal interfaces or seams need to be formalized.
• Skip Level 1 (Capabilities) unless the user-facing scope is actually changing.

Present:

• Current structural problems -- what is wrong with the current shape
• Target structure -- which components, classes, and functions should exist after the refactor
• Movement plan -- what logic moves where
• Preservation boundaries -- what will stay behaviorally unchanged
• Out-of-scope items -- what will not be changed in this pass

End the step with an explicit gate:

"Does this refactor plan look correct? Should I proceed to Step 4: characterization tests?"

STOP: Do not write any refactoring code until the user explicitly approves this plan.

If persistence is enabled, use framework:context-anchoring Enrich to capture the approved preservation boundaries, target structure, movement plan, and out-of-scope items. STOP: When persistence is enabled, do not proceed to Step 4 until the approved plan is written.

Step 4: Add Characterization Protection First

Before changing any structure, lock in current behavior with tests.

• Identify existing tests that already protect preserved behavior.
• Strengthen existing tests that are too implementation-coupled or too vague to serve as guardrails.
• Add characterization tests for important behaviors that are currently implicit.
• Prefer the lowest-level test that faithfully captures each preserved behavior without missing important integration effects.
• Characterization tests must describe the current observable behavior, not the intended refactored shape.
• Apply framework:test-quality inline while writing them.
• Run the safety net where the environment allows. If tests cannot be executed here, say so explicitly — the safety net then counts as unverified, and the stopping rule below applies.

Stopping rule:

• An important preserved behavior is not protected by tests → pause and make that gap explicit before refactoring.
• STOP: Do not start structural edits without a believable safety net unless the user explicitly accepts the risk.
• Green characterization tests are the baseline for the refactor. Anything red before the first structural change must be resolved first, or the task re-scoped.

End the step with an explicit gate:

"Characterization tests in place and passing. Ready to discuss refactor strategy and pacing?"

STOP: Do not proceed to strategy selection until the safety net is verified green — or the user has explicitly accepted an unverified safety net per the stopping rule above.

Step 5: Choose Refactor Strategy and Pacing

With the high-level plan approved and the safety net green, choose the implementation approach.

Preferred strategies:

• Extract and redirect -- extract focused units, route callers gradually.
• Introduce seam, then migrate -- add an interface or boundary, then move behavior behind it.
• Move behavior inward -- shift business rules from outer layers into the appropriate inner layer per framework:architecture.
• Split and collapse -- separate unrelated responsibilities, then remove the old mixed path.

Ask the user to choose a pacing mode:

"How would you like to review the refactor?"

1. Slice-by-slice (recommended) -- refactor one safe slice at a time, pausing after each slice. Best for risky legacy code.
2. Layer-by-layer -- complete the refactor for one structural layer or concern, then pause for review. Best for broader architectural cleanup.
3. Full autonomy -- execute the approved refactor end-to-end and present the complete result at the end. Best for tightly scoped, low-risk refactors. (Still pause immediately if any slice reveals the approved plan unsafe or invalid — see the Deviation Rule in Step 6.)

Default to slice-by-slice when the user expresses no preference.

Step 6: Refactor in Small Green Steps

Implement only within the approved preservation boundaries and the approved target structure.

For each slice:

1. Make one structural improvement from the approved plan.
2. Re-run the relevant characterization tests.
   • Any characterization test goes red → stop immediately. Do not start the next slice. Fix the regression or revert the slice before continuing.
3. Apply the applicable atom Self-Validation Checklists.
4. Run the applicable Active Anti-Pattern Scans.
5. Fix violations before presenting the slice.
6. Collect judgment calls for the slice via framework:collaborative-judgment and surface them before presenting the slice's code. Do not interrupt mid-slice unless the approved plan becomes unsafe or invalid.

Always apply:

• framework:clean-code -- better boundaries, simpler control flow, smaller focused units, clearer naming.
• framework:test-quality -- maintain strong characterization tests and nearby supporting tests.

Conditionally apply:

• Responsibilities move across layers or dependency direction changes → apply framework:architecture.
• Business rules, aggregates, value objects, or domain behavior move or sharpen → apply framework:domain-driven-design.
• Trust boundaries, authorization, validation, queries, or sensitive data handling are touched → apply framework:secure-coding.

Deviation rule: if the implementation reveals the approved plan incomplete, unsafe, or requiring changes to preserved behavior → STOP: pause immediately and discuss before continuing.

Step 7: Verify Preservation and Structural Improvement

The refactor succeeds only if both are true:

1. Behavior preserved
2. Structure measurably better

Verify preservation:

• Characterization tests still pass.
• No unintended outward behavior changed.
• Preserved contracts remain intact.
• Security posture not weakened.

Verify structural improvement:

• Responsibilities clearer.
• Dependency direction improved, or at least no worse.
• Duplication or entanglement reduced.
• Testability and readability improved.
• Old paths and temporary scaffolding removed once migration is complete.

When reporting completion, be explicit about both sides:

• What behavior was preserved and how it was verified.
• What structural improvement was achieved.
• What was intentionally deferred to a later refactor.

Step 8: Capture Decisions and Remaining Debt

Use framework:context-anchoring Enrich to preserve the important parts of the refactor:

• Refactor scope: what area changed.
• Preservation boundaries: what was explicitly kept stable.
• Target structure: what shape was approved.
• Strategy chosen: why this migration path was selected over the alternatives.
• Key files changed: path + role in the doc's Key Files table (skip a path already listed).
• Deferred debt: what remains and why it was intentionally left for later.

No context doc exists and the refactor involved non-trivial structural reasoning → suggest creating one so the decisions are not lost across sessions.

Harvest learnings: run framework:learning-harvest Harvest behavior. Session context: "refactoring session — structural restructuring and debt resolution". Synthesize and propose cross-cutting patterns from this session — structural debt that accumulated, migration strategies that worked, characterization test gaps discovered. The user confirms what enters the document. STOP: run this before recommending /review below.

After the refactor is complete, recommend /review when the change:

• touches multiple layers
• changes domain boundaries
• changes security-sensitive code
• leaves temporary migration scaffolding behind
• is large enough that an independent quality pass would add confidence