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 (tech stack, architecture, conventions) so refactor fits real project not generic patterns (always)
2. `framework:context-anchoring` -- Load existing feature context doc when available, capture approved refactor plan, preservation rules, structural decisions for future sessions (always)
3. `framework:learning-harvest` -- Load prior operational learnings inform refactor; harvest new patterns at session end (always)
4. `framework:collaborative-judgment` -- Surface meaningful trade-offs in structure, seams, migration sequence instead of silently choosing path (always)
5. `framework:clean-code` -- Improve readability, responsibility boundaries, local code craft while preventing scope creep and wrong abstractions (always)
6. `framework:test-quality` -- Lock current behavior with characterization tests, keep safety net reliable throughout refactor (always)
7. `framework:design-first` -- Use progressive design selectively for significant structural changes so target structure agreed before editing code (conditional)
8. `framework:architecture` -- Validate layer placement, dependency direction, correct structural boundaries (conditional)
9. `framework:domain-driven-design` -- Validate domain behavior, aggregate boundaries, movement of business rules into correct domain objects (conditional)
10. `framework:secure-coding` -- Preserve validation, authorization, trust-boundary protections, safe data handling when refactor touches security-sensitive code (conditional)

## Workflow

### Step 1: Establish Refactor Context

Start from **current pain**, not preferred abstraction.

- Identify target area: module, service, aggregate, endpoint path, subsystem
- Clarify **why** refactor needed: mixed responsibilities, duplication, wrong-layer logic, coupling, poor testability, unreadable control flow
- Clarify what user expects to improve: simpler structure, correct layer placement, smaller units, clearer domain behavior, easier testing, safer extension points
- Use `framework:learning-harvest` Load behavior. Focus hint: "refactoring session — focus: structural health, quality signals". Prior learnings about debt patterns, recurring structural issues, and coupling problems inform which structural mistakes to prioritize correcting.
- Use `framework:context-anchoring` Document Discovery to check for existing context doc for affected feature/module
  - **If found** → Load it (context-anchoring Load behavior). Honor existing decisions and constraints as active commitments while planning refactor
  - **If not found** → Proceed from conversation and current code. Don't block planning on missing context

End step, summarize intent one sentence:

> "Refactor X to improve Y while preserving Z."

If can't state improvement target and preservation target that clearly yet, continue clarifying before planning changes.

**Optional persistence check**:

- If refactor substantial, risky, or likely span multiple sessions, ask whether user wants persist approved plan
- If relevant context doc already exists and user wants persistence → load and update it
- If no relevant doc exists and user wants persistence → propose creating one, confirm doc name per `framework:context-anchoring`, then use as source of truth for approved plan
- If user doesn't want persistence or refactor small and local → continue in non-persistent mode. Approval gates still apply; plan simply remains in-session

### Step 2: Define Preservation Boundaries

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

List 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 where externally visible
- Performance or operational characteristics if part of current contract

Also list explicit **out-of-scope changes**:

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

This step defines refactor's safety boundary. If desired outcome requires changing preserved behavior, stop and discuss whether task actually bug fix, feature, or broader redesign.

### Step 3: Propose High-Level Structural Plan

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

For small refactors, 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 formalized
- Don't use Level 1 (Capabilities) unless user-facing scope actually changing

Present:

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

End step with explicit gate:

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

Don't write refactor code until user explicitly approves.

If persistence enabled, use `framework:context-anchoring` Enrich behavior to capture approved preservation boundaries, target structure, movement plan, out-of-scope items. Don't proceed to Step 4 until plan written.

### Step 4: Add Characterization Protection First

Before changing structure, lock current behavior with tests.

- Identify existing tests that already protect preserved behavior
- Strengthen wea