markitect-main/examples/design-patterns/CopyFirstMigration.md

Design Principle: Copy First Migration

Meta

• Name: Copy First Migration
• ShortName: CopyFirst
• Version: 0.1
• Status: Draft
• Tags: refactoring, migration, safety, testing, legacy
• RelatedPrinciples: Don’t Repeat Yourself, Safe Refactoring, Test Pyramid, Capability-Based Testing

---

Intent

Enable safe refactoring and structural migration of codebases by preserving existing, working functionality until the new implementation is fully verified.

This principle prioritizes reversibility, confidence, and continuity over speed or elegance.

---

CoreStatement

Never move code directly; always copy first and delete only after verified behavioral equivalence is established.

---

Scope

InScope

• Large-scale refactors or directory restructurings
• Technology or language migrations (e.g. JS → new JS layout, JS → Python integration)
• Legacy code stabilization
• Safety-critical or business-critical systems
• Situations with incomplete test coverage

OutOfScope

• Greenfield development
• Trivial refactors with full and trusted test coverage
• One-off throwaway scripts
• Performance-driven rewrites where duplication is unacceptable

---

InterpretationGuidelines

What “Copy First” Means

• The original code remains untouched and functional
• The new version is treated as experimental until proven
• Deletion is a final, explicit act, not an implicit side effect

Common Misinterpretations

• “This is inefficient because it duplicates code”
  → Duplication is intentional and temporary
• “Moving files is faster”
  → Speed is not the optimization target here
• “Tests alone are enough”
  → Tests are necessary but not sufficient without behavioral comparison

---

DetectionHeuristics

Structural Signals

• Files or modules being relocated across directories or packages
• Parallel implementations during migration
• Introduction of a new architectural boundary

Semantic Signals

• Code paths that must remain behaviorally identical
• Business rules with high regression risk
• Legacy logic that is poorly documented but relied upon

Change-Cost Signals

• Rollbacks are expensive or disruptive
• Failures would impact production or customers
• Migration spans multiple commits or teams

---

DiagnosticQuestions

1. What breaks if this migration is wrong?
2. Do we have a known-good reference implementation?
3. Can both old and new code paths run in parallel?
4. How quickly can we revert if a defect is found?
5. What is the minimal proof of behavioral equivalence?

---

RecommendedActions

Low-Risk Actions

• Copy files to the new location instead of moving
• Preserve original imports and entry points
• Add logging or tracing for comparison

Medium-Risk Actions

• Introduce dual-track execution (old + new)
• Add integration tests targeting both implementations
• Compare outputs, side effects, and error behavior

High-Risk Actions

• Switch production usage to the new implementation
• Remove old code only after full verification
• Collapse duplicated paths once confidence is established

---

AcceptanceCriteria

• Original code remains functional until final removal
• New code passes all existing tests
• New integration tests validate identical behavior
• Dual-track comparisons show no regressions
• Deletion of old code is deliberate and reversible up to the final step

---

AntiPatterns

• Moving files directly without a fallback
• Refactoring and migration in a single irreversible step
• Deleting “unused” code before equivalence is proven
• Assuming test parity guarantees behavioral parity
• Big-bang migrations without rollback paths

---

Tradeoffs

Applying Copy First Migration intentionally:

• Introduces temporary duplication
• Increases short-term codebase size
• Slows perceived progress

These costs are justified by dramatically reduced risk and higher confidence during complex migrations.

---

AgentUsage

When to Apply This Lens

• During directory, module, or architecture migrations
• When refactoring legacy or poorly understood code
• When safety and uptime matter more than speed
• When rollback must remain possible at all times

When to Suspend This Lens

• In greenfield projects
• When full test coverage and confidence already exist
• For trivial mechanical refactors

Expected Agent Output

• Identification of migration boundaries
• Copy-first migration plan with explicit stages
• Test strategy (unit, integration, dual-track)
• Rollback points and deletion criteria
• Clear signal for when old code may be removed

xxx