# Save Data Schema Migration

> Use when versioning or converting serialized player save files, profiles, checkpoints, or persistence payloads across recognized save-format versions with fixture compatibility and rollback.

- Skill: `hoatv2211/save-data-schema-migration` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add hoatv2211/save-data-schema-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoatv2211/save-data-schema-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: hoatv2211 (https://skillmd.com/u/hoatv2211)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hoatv2211/save-data-schema-migration

---

# Save Data Schema Migration

## Overview
Plan and test player-save migrations through an explicit version chain while preserving the original payload and refusing unknown or newer versions.

## When to use
Use for save field renames, defaults, removals, version upgrades, backward compatibility, import migrations, or player-data format changes.

## When NOT to use
Do not use for database schema migration, arbitrary config edits, or direct production player-save rewrites without a project runbook.

## Required inputs and context discovery
Require current and target versions, migration chain, save authority, fixture set, backup scope, rollback method, compatibility window, reviewer, human approval, privacy constraints, and validation checks.

## Safety and risk level
High-risk. Unknown versions, incomplete chains, missing backup, missing rollback, missing reviewer, live player data, or missing approval means BLOCKED.

## Workflow
1. Identify save authority, current version, target version, and supported compatibility range.
   Completion criterion: unknown or newer versions are BLOCKED.
2. Review each one-version migration step for rename, default, removal, and data loss.
   Completion criterion: irreversible transformations are explicit.
3. Preserve the original fixture and run migration on a copy.
   Completion criterion: fixture mutation cannot destroy rollback input.
4. Validate migrated semantics and backward/forward compatibility expectations.
   Completion criterion: expected fields and values are asserted.
5. Prepare exact backup, apply, rollback, reviewer, and approval evidence for real scope.
   Completion criterion: real player data remains untouched until authorized.

## Evidence and output contract
Produce `save-migration-plan.json` with versions, migration hashes, fixture results, compatibility, rollback, reviewer, approval, verdict, and limitations.

## Handoff contract
Record save authority, version chain, fixture paths, migration result, data-loss risks, backup/rollback, approval state, and next authorized action.

## Pitfalls and anti-rationalization
- Never guess an unknown save version.
- A successful JSON parse is not semantic compatibility.
- Do not test with the only copy of a player save.
- Database migration safety is a separate workflow.

## Verification checklist
- [ ] Version chain is complete.
- [ ] Original fixture is preserved.
- [ ] Migration and rollback are tested.
- [ ] Compatibility risks are explicit.
- [ ] Reviewer and human approval gate real apply.

## References and scripts
Use the bundled [scripts/save_migration.py](scripts/save_migration.py) for isolated fixtures and `safe-project-mutation` for authorized file application.