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.