home / skills / shotaiuchi / dotclaude / migration-rollback

migration-rollback skill

safe

This skill helps design safe migration rollback procedures, feature flags, and monitoring to ensure quick, data-safe reversions with minimal downtime.

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

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-rollback
description: >-
  Rollback planning for migrations. Apply when designing rollback procedures,
  feature flags, safe fallback paths, rollback triggers, and step-by-step
  revert instructions.
user-invocable: false
---

# Rollback Planning

Design safe rollback procedures for migration.

## Migration Checklist

### Rollback Procedures
- Define step-by-step revert instructions for each migration phase
- Verify rollback scripts restore previous state completely
- Ensure rollback can be performed without data loss
- Document estimated rollback time and required resources

### Feature Flags & Toggles
- Implement feature flags to enable gradual rollout
- Verify flags can disable new behavior without redeployment
- Check that flag state is consistent across all services
- Ensure flag cleanup plan exists after migration completes

### Rollback Triggers
- Define measurable criteria that trigger automatic rollback
- Set up monitoring alerts for error rate and latency spikes
- Establish clear escalation path when triggers are hit
- Verify rollback can be initiated both manually and automatically

### Recovery Verification
- Validate system health after rollback execution
- Confirm data consistency between rolled-back components
- Run smoke tests to verify core functionality is restored
- Check that dependent systems are notified of rollback

## Output Format

Report findings with risk ratings:

| Risk | Description |
|------|-------------|
| Critical | No rollback path exists, migration is irreversible |
| High | Rollback possible but may cause data inconsistency |
| Medium | Rollback requires manual steps but is achievable |
| Low | Clean rollback with automated procedures available |

Overview

This skill helps teams design and validate rollback plans for migrations. It guides creation of step-by-step revert instructions, feature flag strategies, rollback triggers, and verification checks to ensure safe fallbacks. Use it to reduce risk and restore service quickly when a migration goes wrong.

How this skill works

The skill inspects migration phases and produces concrete rollback procedures, checks for automated rollback scripts, and verifies that recovery steps preserve data consistency. It evaluates feature flag implementations, defines measurable rollback triggers, and outlines verification steps and required resources. Finally, it classifies findings into risk ratings to prioritize remediation.

When to use it

When designing a database or schema migration that could affect live traffic
Before deploying a new feature that requires coordinated changes across services
When introducing feature flags or toggles as part of a rollout strategy
Prior to running a production migration or large-scale deploy
When updating runbooks and incident response plans for release safety

Best practices

Write explicit, repeatable rollback scripts that restore previous state without manual intervention
Implement feature flags that can disable new behavior instantly and consistently across services
Define measurable rollback triggers (error rate, latency, data drift) and automations for them
Document estimated rollback time, required personnel, and resource constraints upfront
Include post-rollback verification: smoke tests, data consistency checks, and downstream notifications

Example use cases

Prepare a rollback plan for a zero-downtime schema migration with both automated and manual paths
Validate that feature toggles can disable a new service behavior without redeploying code
Create escalation and automatic rollback criteria that trigger on service-level SLO breaches
Produce a step-by-step revert runbook for on-call engineers with estimated execution time
Audit an existing migration pipeline and assign risk ratings to missing rollback controls

FAQ

How do I choose rollback triggers?

Select measurable signals tied to user impact (error rate, latency, throughput, data integrity checks) and set thresholds that balance sensitivity with noise to avoid unnecessary rollbacks.

Can rollbacks be safe for destructive migrations?

Destructive changes require careful pre-migration backups, reversible transformation plans, or phased rollouts. If irreversibility remains, classify risk as Critical and avoid production rollout until mitigations exist.