Planning Refactors With AI — Plans First, Code Second

1. EXPLORE   — Agent reads the relevant code, summarizes architecture
2. PROPOSE   — Agent writes a refactor plan: goals, non-goals, steps, risks
3. REVIEW    — You read and edit the plan. NO CODE TOUCHED YET.
4. EXECUTE   — Agent implements ONE step at a time, running tests between each
5. STOP      — At any failure or surprise, stop and replan

"Don't write any code. Read src/auth/ and produce a refactor plan with these sections:

1. CURRENT STATE
   - What does this module do?
   - What's the architecture (1-paragraph)?
   - What are its public exports?

2. PROBLEMS YOU SEE (concrete, with file:line references)

3. GOALS — what should be true after the refactor?

4. NON-GOALS — explicitly NOT changed (write 5-10 of these)

5. STEPS — numbered, each step:
   - 1-line description
   - Files touched
   - Risk level (low/med/high)
   - How we'll know the step succeeded (test command)

6. RISKS
   - What could go wrong?
   - What's the rollback for each step?

Return this as Markdown. Do not edit any files."

# After plan is approved:

"Execute step 1 only. Run the verify command. Show me the diff and the test output.
Do not start step 2 until I confirm step 1 is good."

# Then, after each step:
# - Read the diff
# - Run tests yourself
# - Commit the step (atomic commit per step)
# - Approve next step

# Most teams using this approach see ~3-5 minute review per step,
# 5-10 minute execution per step. A 10-step refactor takes ~2 hours
# and ships clean instead of taking a day and breaking things.

# Generate an ADR from the plan:

"Convert section 3 of the refactor plan into an ADR with these sections:
  - Context (why this is being considered now)
  - Decision (what we're doing)
  - Status (proposed)
  - Consequences (positive, negative, neutral)
  - Alternatives considered (at least 2, with why-rejected)

Number the ADR sequentially based on existing files in docs/adr/."