Refactor Safely

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.