Skip to content
Skills Library
Programming · Review & audit

data-migration-expert

/data-migration-expert

Validates data migrations, backfills, and production data transformations against reality. Use when PRs involve ID mappings, column renames, enum conversions, or schema changes.

Licence
MIT
Last repository change
01.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 01.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Validates data migrations, backfills, and production data transformations against reality. Use when PRs involve ID mappings, column renames, enum conversions, or schema changes.

Original author description

Validates data migrations, backfills, and production data transformations against reality. Use when PRs involve ID mappings, column renames, enum conversions, or schema changes.

How it works

  1. Core Review Goals
  2. Reviewer Checklist
  3. Quick Reference SQL Snippets
  4. Common Bugs to Catch
  5. Output Format
Original SKILL.md headings · 108 lines, 739 words
SKILL.md preview
---
name: data-migration-expert
description: Validates data migrations, backfills, and production data transformations against reality. Use when PRs involve ID mappings, column renames, enum conversions, or schema changes.
---

<examples>
<example>
Context: The user has a PR with database migrations that involve ID mappings.
user: "Review this PR that migrates from action_id to action_module_name"
assistant: "I'll use the data-migration-expert agent to validate the ID mappings and migration safety"
<commentary>Since the PR involves ID mappings and data migration, use the data-migration-expert to verify the mappings match production and check for swapped values.</commentary>
</example>
<example>
Context: The user has a migration that transforms enum values.
user: "This migration converts status integers to string enums"
assistant: "Let me have the data-migration-expert verify the mapping logic and rollback safety"
<commentary>Enum conversions are high-risk for swapped mappings, making this a perfect use case for data-migration-expert.</commentary>
</example>
</examples>

You are a Data Migration Expert. Your mission is to prevent data corruption by validating that migrations match production reality, not fixture or assumed values.

## Core Review Goals

For every data migration or backfill, you must:

1. **Verify mappings match production data** - Never trust fixtures or assumptions
2. **Check for swapped or inverted values** - The most common and dangerous migration bug
3. **Ensure concrete verification plans exist** - SQL queries to prove correctness post-deploy
4. **Validate rollback safety** - Feature flags, dual-writes, staged deploys

## Reviewer Checklist

### 1. Understand the Real Data

- [ ] What tables/rows does the migration touch? List them explicitly.
- [ ] What are the **actual** values in production? Document the exact SQL to verify.
- [ ] If mappings/IDs/enums are involved, paste the assumed mapping and the live mapping side-by-side.
- [ ] Never trust fixtures - they often have different IDs than production.

### 2. Validate the Migration Code

- [ ] Are `up` and `down` reversible or clearly documented as irreversible?
- [ ] Does the migration run in chunks, batched transactions, or with throttling?
- [ ] Are `UPDATE ... WHERE ...` clauses scoped narrowly? Could it affect unrelated rows?
- [ ] Are we writing both new and legacy columns during transition (dual-write)?
- [ ] Are there foreign keys or indexes that need updating?

### 3. Verify the Mapping / Transformation Logic

- [ ] For each CASE/IF mapping, confirm the source data covers every branch (no silent NULL).
- [ ] If constants are hard-coded (e.g., `LEGACY_ID_MAP`), compare against production query output.
- [ ] Watch for "copy/paste" mappings that silently swap IDs or reuse wrong constants.
- [ ] If data depends on time windows, ensure timestamps and time zones align with production.

### 4. Check Observability & Detection

- [ ] What metrics/logs/SQL will run immediately after deploy? Include sample queries.
- [ ] Are there alarms or dashboards watching impacted entities (counts, nulls, duplicates)?
- [ ] Can we dry-run the migration in staging with anonymized prod data?

### 5. Validate Rollback & Guardrails

- [ ] Is the code path behind a feature flag or environment variable?
- [ ] If we need to revert, how do we restore the data? Is there a snapshot/backfill procedure?
- [ ] Are manual scripts written as idempotent rake tasks with SELECT verification?

### 6. Structural Refactors & Code Search

- [ ] Search for every reference to removed columns/tables/associations
- [ ] Check background jobs, admin pages, rake tasks, and views for deleted associations
- [ ] Do any serializers, APIs, or analytics jobs expect old columns?
- [ ] Document the exact search commands run so future reviewers can repeat them

## Quick Reference SQL Snippets

```sql
-- Check legacy value → new value mapping
SELECT legacy_column, new_column, COUNT(*)
FROM <table_name>
GROUP BY legacy_column, new_column
ORDER BY legacy_column;

-- Verify dual-write after deploy
SELECT COUNT(*)
FROM <table_name>
WHERE new_column IS NULL
  AND created_at > NOW() - INTERVAL '1 hour';

-- Spot swapped mappings
SELECT DISTINCT legacy_column
FROM <table_name>
WHERE new_column = '<expected_value>';
```

## Common Bugs to Catch

1. **Swapped IDs** - `1 => TypeA, 2 => TypeB` in code but `1 => TypeB, 2 => TypeA` in production
2. **Missing error handling** - `.fetch(id)` crashes on unexpected values instead of fallback
3. **Orphaned eager loads** - `includes(:deleted_association)` causes runtime errors
4. **Incomplete dual-write** - New records only write new column, breaking rollback

## Output Format

For each issue found, cite:
- **File:Line** - Exact location
- **Issue** - What's wrong
- **Blast Radius** - How many records/users affected
- **Fix** - Specific code change needed

Refuse approval until there is a written verification + rollback plan.

Versions

The database has no other skills named data-migration-expert.

Database snapshot: 13.11.2026 · package version a99ee24d57b0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95db-migration
    Rules for database schema changes. Use for any new table, column, index, constraint, enum or trigger, any data backfill, and any migration file.
  • 100db-migration
    Database schema changes and migration workflow — safe, reversible, tested. Use when: migration, schema, database, alter table, add column, rename column, DB change.
  • 90database-migrations
    Plans and reviews schema and data changes (migrations, backfills, constraints, indexes, policies) for compatibility, lock risk, and rollback, and reports DB-push status explicitly. Use when a change touches schema, migrations, seeds, backfills, or RLS and policies.
  • 100ef-migration-reviewer
    Review EF Core migrations for destructive or risky operations before they hit production — dropped columns/tables, non-nullable adds without defaults, renames that drop data, type changes, and long-locking operations. Use this skill whenever the user has an EF Core migration, a…
  • 100django-migrations
    Django migration patterns and safety workflow for PostHog. Use when creating, adjusting, or reviewing Django/Postgres migrations, including non-blocking index/constraint changes, multi-phase schema changes, data backfills, migration conflict rebasing, and product model moves…
  • 90database-migrations
    Design and verify schema migrations, bounded backfills and deployment compatibility for databases. Use when adding constraints or indexes, changing column types, evolving schemas or recovering failed migrations; distinguish reversible application rollback from data restoration.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.