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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ForeverSc
• Source: ForeverSc/ai-handrail
• License: MIT

Install and usage instructions live in the source repository linked above.