Refactor Planner

This workflow creates a refactoring plan that is incremental, testable, and low-risk.

Purpose & Scope

Use this workflow when:

• •You are asked to refactor, restructure, or 鈥渃lean up鈥?code
• •You detect systemic issues (duplication, tight coupling, large files) that need planning

Out of scope:

• •Executing the refactor (use the refactor execution workflow)

Inputs & Preconditions

Inputs:

• •Target area (files/directories/modules)
• •Motivation (maintainability, performance, correctness, consistency)
• •Constraints (deadlines, compatibility requirements, approvals)

Preconditions:

• •Read the most local applicable AGENTS.md.
• •Identify whether the change is single-module or cross-module (integration scenario).

Steps

1. •Current state analysis
   • •Inventory files, responsibilities, and dependency edges.
2. •Identify issues
   • •Duplication, long functions/classes, circular deps, unclear boundaries, poor naming.
3. •Define target architecture
   • •Proposed layout and responsibilities (small, composable units).
4. •Plan phases
   • •Break into atomic steps that preserve behavior.
   • •Specify intermediate states that still build/test.
5. •Risk & rollback
   • •Identify breaking points and rollback strategy per phase.
6. •Testing strategy
   • •What to test per phase (unit/integration/contract).
7. •Acceptance criteria
   • •Define measurable success and DoD.

Outputs

• •A refactor plan document with:
  • •Executive summary
  • •Current state analysis
  • •Proposed structure
  • •Step-by-step phases
  • •Risks + mitigations
  • •Testing + rollback

Safety Notes

• •Cross-module refactors require coordination and often human approval.
• •Avoid mixing behavior changes with structural moves unless explicitly intended.