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.
