home / skills / shotaiuchi / dotclaude / migration-compatibility

migration-compatibility skill

safe

/dotclaude/skills/migration-compatibility

This skill helps design and evaluate migration compatibility layers, adapters, and abstractions to ensure safe, incremental coexistence of old and new systems.

npx playbooks add skill shotaiuchi/dotclaude --skill migration-compatibility

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.7 KB

---
name: migration-compatibility
description: >-
  Compatibility layer design for migrations. Apply when creating adapters,
  shims, polyfills, abstraction layers, and incremental migration bridges
  between old and new systems.
user-invocable: false
---

# Compatibility Bridge Design

Design compatibility layers to bridge old and new systems during migration.

## Migration Checklist

### Adapter Design
- Define adapter interfaces for changed APIs
- Implement wrappers that translate old calls to new APIs
- Ensure adapters handle edge cases from both versions
- Verify adapter performance overhead is acceptable

### Abstraction Layers
- Create version-agnostic abstractions over divergent APIs
- Isolate version-specific code behind clean interfaces
- Ensure abstractions do not leak implementation details
- Validate abstraction coverage for all affected call sites

### Incremental Migration Path
- Define phase-by-phase migration milestones
- Ensure each phase produces a working system
- Identify safe stopping points for partial migration
- Provide rollback capability at each migration phase

### Coexistence Strategy
- Verify old and new code can run side by side
- Check for shared state conflicts between versions
- Ensure dependency versions do not clash at runtime
- Validate integration tests cover coexistence scenarios

## Output Format

Report findings with risk ratings:

| Risk | Description |
|------|-------------|
| Critical | No viable compatibility path, redesign required |
| High | Complex bridging needed, significant effort required |
| Medium | Standard adapter pattern sufficient, moderate effort |
| Low | Minor shim needed, straightforward implementation |

Overview

This skill helps design compatibility layers and migration bridges to connect legacy and modern systems. It focuses on adapters, abstraction layers, coexistence strategies, and phased migration plans to reduce disruption. The output is a pragmatic checklist and a risk-rated report to guide implementation choices.

How this skill works

The skill inspects API differences, shared state, dependency versions, and runtime interactions to define adapters or shims. It maps call sites to version-agnostic abstractions, specifies incremental migration phases with rollback points, and evaluates coexistence risks. Finally it produces findings with risk ratings (Critical, High, Medium, Low) to prioritize work.

When to use it

When replacing core services but keeping parts of the legacy system running
When introducing new APIs that are incompatible with existing callers
When building an adapter, shim, or polyfill to avoid mass refactor
When planning phased, reversible migrations to minimize outage risk
When validating that multiple versions can run concurrently in production

Best practices

Define clear adapter interfaces that translate intent, not just signature
Isolate version-specific code behind small, testable abstractions
Design each migration phase to deliver a working system and a safe rollback path
Validate coexistence with integration tests covering shared-state and dependency conflicts
Measure adapter performance and ensure overhead stays within acceptable limits
Document safe stopping points and criteria for advancing phases

Example use cases

Create an adapter layer that translates legacy API payloads to the new API format with error mapping and retries
Design a version-agnostic service facade that hides divergent client libraries behind a single interface
Implement an incremental migration plan: feature flag, partial roll out, monitor, then shift traffic
Build shims to emulate deprecated behavior while new implementations are deployed
Run coexistence tests that simulate mixed-version traffic and check for state corruption

FAQ

What should I evaluate first when designing a compatibility layer?

Start by cataloging API differences, shared state points, and runtime dependencies; map all affected call sites to prioritize adapters.

How do I decide risk rating for a migration task?

Assess feasibility of translation, required effort, potential for data loss, and ability to roll back; use Critical/High/Medium/Low to communicate urgency and effort.