/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 test