Refactoring & Migration Playbook

This playbook guides missions involving code modernization, architecture migrations, dependency upgrades, or large-scale refactoring. The core challenge: change implementation while preserving behavior.

Key Principle: Tests Before Changes

Refactoring without tests is just changing code and hoping. Before modifying any code:

• If tests exist: ensure they pass and cover the behavior you're changing
• If tests are missing: add characterization tests that capture current behavior first

Milestone Strategy: Incremental Safe Transformation

Structure milestones around safe transformation phases:

• characterization - Add tests capturing current behavior (if missing)
• scaffold - Set up new patterns/infrastructure alongside old (strangler fig)
• migrate-batch-N - Migrate components incrementally, tests pass after each batch
• cutover - Switch to new implementation, remove old code
• cleanup - Remove scaffolding, polish