Legacy refactor plan

Legacy Refactor Plan

Break modernization into small, safe, verifiable tasks that AI can execute within controlled boundaries.

Goal

Produce a sequence of refactoring tasks where each task is independently verifiable, reversible, and auditable — never a big-bang rewrite.

When to Use

• After guardrails exist (via legacy-safety-rails)
• When the user wants to start actual code modifications
• When planning a migration, extraction, or modernization

Mandatory Workflow

Step 1: Confirm Prerequisites

Before planning any refactor, verify:

• Discovery completed for the target area?
• Documentation exists for affected modules?
• Test guardrails cover P0 paths through this area?
• Rollback procedure documented?
• Dependency versions identified and locked?
• High-impact outdated dependencies verified from the lockfile, project usage, and source inspection?

If any prerequisite is missing, stop and complete it first using the appropriate skill.

Step 2: Define Refactor Scope

With the user, agree on:

1. What is being refactored (specific module, pattern, dependency)
2. Why (the business or technical motivation)
3. Boundary — what must NOT change (APIs, contracts, behaviors)
4. Success criteria — how do we know it's done correctly?

Step 3: Choose Refactoring Strategy

Prefer safe strategies in this order:

1. Wrap — add an adapter/wrapper around old code at identified seams (see discovery seam inventory), redirect callers gradually
2. Strangle (Strangler Fig) — build new implementation alongside old, insert Anti-Corruption Layer between them, switch traffic incrementally
3. Extract — pull a module into a cleaner boundary without changing its logic
4. Replace — swap implementation behind a stable interface (only with tests + feature flag)
5. Rewrite — last resort, small scope only, requires maximum guardrails

Anti-Corruption Layer: When new code must interact with legacy code, insert an isolation layer that translates between models. The ACL prevents legacy concepts from leaking into new code. When the legacy system is eventually replaced, only the ACL needs to change. See docs/methodology.md → Anti-Corruption Layer.

Seam-based approach: Use seams identified during discovery as attachment points for wrappers and adapters. If no seams were identified for the target area, run a focused discovery round first.

Step 4: Decompose into Tasks

Break the refactor into tasks. Each task MUST include:

## Task: [short description]

**Objective**: What this task accomplishes
**Files**: List of files to be modified
**Invariants**: What must NOT change (contracts, behavior, interfaces)
**Pre-conditions**:
  - [ ] Tests to add/verify before this task
  - [ ] Baseline captured for affected behavior

**Steps**:
1. [specific action]
2. [specific action]
...

**Verification**:
- [ ] Existing tests pass
- [ ] New tests pass
- [ ] Behavior matches baseline
- [ ] [domain-specific checks]

**Rollback**:
- [how to undo this task]

**Human Review Required**: [yes/no] — [reason if yes]

Use the template from templates/refactor-task.md.

Step 5: Order Tasks

Sequence tasks so that:

1. Each task is independently deployable
2. Earlier tasks don't depend on later tasks
3. Highest-risk tasks have the most guardrails
4. Tasks that add tests come before tasks that change code

Step 6: Execute One Task at a Time

For each task:

1. Read the task specification
2. Verify pre-conditions are met
3. Execute the steps
4. Run all verification checks
5. If verification fails — rollback, don't proceed
6. Update documentation to reflect changes
7. Move to next task only after human sign-off (if required)

Required Outputs

Output	Description
Prerequisites checklist	Verified list of discovery, docs, and guardrails in place
Scope agreement	Documented boundary, invariants, and success criteria
Strategy rationale	Why this refactoring approach was chosen
Task list	Ordered sequence of tasks per the template
Dependency graph	Which tasks depend on which
Human review map	Which tasks need human sign-off and why

Hard Rules

1. One task, one boundary. Each task modifies one well-defined area. No "refactor modules A, B, and C" in one task.
2. Tests before changes. If a task changes code, the tests covering that code must exist and pass before the task starts.
3. Existing versions only. Refactored code must work with the project's actual dependency versions. Upgrades are separate tasks.
4. Use source inspection for risky old dependencies. You must confirm the pinned API via source inspection before changing call sites.
5. Wrap, don't rewrite. Prefer adapter/strangler patterns over rewrites. Rewrites are last resort.
6. Prove equivalence. Before removing old code, demonstrate that new code produces identical behavior via tests or comparison.
7. No drive-by improvements. Only change what the task specifies. Don't "improve" adjacent code.
8. Document as you go. Update docs after each task. Future AI sessions depend on accurate docs.
9. Stop on uncertainty. If a task reveals unexpected complexity, stop and create a new discovery round — don't push through.

Anti-Patterns

Don't	Do instead
Plan a big-bang migration	Break into 5-20 small independent tasks
Assume latest API compatibility	Verify every API against lockfile versions
Remove old code before new code is proven	Run both in parallel, compare, then cut over
Combine test-writing with refactoring in one task	Separate "add tests" and "refactor" into distinct tasks
Skip human review for P0-CRITICAL changes	Always flag P0 changes for human sign-off
Continue when a verification check fails	Stop, rollback, investigate, re-plan

Human Review Triggers

These ALWAYS require human sign-off before proceeding:

• Any change to P0-CRITICAL or LEGACY-SEALED modules
• Any API contract change (paths, parameters, response shapes)
• Any database schema migration
• Any change to analytics/tracking events
• Any deletion of code or files
• Any change to authentication or authorization logic
• Any change to payment or billing flows
• Any behavior change visible to end users