refactoring

# Refactoring (Deep Workflow) Refactoring changes **structure**, not **behavior**. Safety comes from **small steps**, **fast feedback**, and verification (tests, golden outputs, or controlled manual checks). ## When to Offer This Workflow **Trigger conditions:** - Code is hard to change; duplication; unclear module boundaries - Need to prepare an area for a new feature without mixing behavior change - Paying down tech debt with management expecting “no user-visible change” **Initial offer:** Use **six stages**: (1) clarify goal & scope, (2) establish safety net, (3) plan increments, (4) execute with reviewable commits, (5) verify behavior, (6) document & follow-ups). Confirm test coverage and release pressure. --- ## Stage 1: Clarify Goal & Scope **Goal:** Why refactor now—reduce coupling, enable feature X, remove dead code, improve naming. **Exit condition:** Explicit **non-goals** (no feature changes in this effort unless separately scoped). --- ## Stage 2: Establish Safety Net **Goal:** Prefer characterization tests for legacy; golden outputs for data pipelines; use snapshot tests sparingly. ### If tests are weak - Approval tests, short exploratory scripts, or pair review with domain expert --- ## Stage 3: Plan Increments **Goal:** Small commits, each leaving the codebase **working** (not necessarily perfect). ### Practices - Move code, then change behavior in separate steps (Fowler-style when helpful) - Separate mechanical renames from logic edits for reviewability --- ## Stage 4: Execute With Reviewable Commits **Goal:** Each PR/commit tells a story; avoid thousand-line “cleanup” dumps. --- ## Stage 5: Verify Behavior **Goal:** CI green; compare outputs for batch jobs; manual smoke on critical paths when needed. --- ## Stage 6: Document & Follow-Ups **Goal:** ADR or short module README for new boundaries; tickets for remaining debt accepted consciously. --- ## Final Review Checklist - [ ] Scope and non-goals explicit - [ ] Safety net matches risk - [ ] Incremental, reviewable steps - [ ] Behavior verified - [ ] Follow-up debt tracked ## Tips for Effective Guidance - Keep refactor commits separate from feature commits when possible. - If behavior must change, it is not “pure refactoring”—plan as a migration with communication. - Under hotfix pressure, minimize refactor scope or defer. ## Handling Deviations - **Strangler** refactors: maintain adapters at boundaries until cutover is complete.