A skill for migrations and refactors where the behavior must not change. It captures the reference branch's intended behavior, distinguishes contracts that must stay stable from internals that may move, and verifies parity.
---
name: migration-parity-check
description: Use when migrating/refactoring and behavior must stay identical, or before implementing tricky logic (redirects, env hydration). Triggers on 'preserve behavior', 'parity with master'.
---
Use when migrating/refactoring and behavior must stay identical, or before implementing tricky logic (redirects, env hydration). Triggers on 'preserve behavior', 'parity with master'.
Method:
1. Study the master/reference branch to capture intended behavior; document it with a Mermaid diagram.
2. Distinguish external/public fields (must stay backward compatible) from internal fields (may change).
3. Implement, then verify parity: what works on master must work on the branch.
4. Validate against tests; add tests for the parity-critical paths.Capture behavior before you touch it#
Step 1 documents what the reference branch actually does — often as a diagram — so "identical behavior" is measured against a written baseline rather than memory.
Public versus internal#
Step 2 is the judgment call that prevents both over- and under-constraining the refactor: external fields must stay backward compatible, while internal ones are free to change. Tests then pin the parity-critical paths.
What counts as proof#
Proof can be fixture output, API snapshots, screenshots, generated artifacts, database rows, or contract tests. It depends on what the old path promised to the caller.
The mistake is comparing implementation shape instead of behavior. A migration can change internals freely if the public contract, edge cases, and failure behavior still match.