magnus919_agent-skills/migration-engineering/references/recovery-classification.md

# Recovery Classification

Deep reference on the four recovery paths with decision rules, examples, and
anti-patterns. Load this reference when classifying recovery for concrete
migration steps.

## The four recovery paths

### Rollback

Reverse to the prior state by undoing the change.

**Decision rule:** Rollback is possible when the old state still exists and can
be reactivated, OR the change is purely additive and can be removed without side
effects.

**Examples:**
- Undo a feature-flag-controlled code path by turning off the flag.
- Restore read traffic to the old database by reverting the connection string.
- Drop a newly added nullable column that is not yet consumed.
- Cancel a deprecation notice and keep the old API endpoint live.

**Anti-patterns:**
- Claiming rollback is possible because "we can fix it in the next deploy."
  That is roll-forward, not rollback.
- Claiming rollback is possible when the old system has been decommissioned.
  That is restore or irreversible.

### Roll-forward

Fix forward in the new state. The old state is no longer reachable, but a fix
can be deployed to the new system.

**Decision rule:** Roll-forward is the correct path when (a) reversal is
impossible or more expensive than fixing forward, AND (b) a fix can be deployed
within the acceptable recovery window.

**Examples:**
- A data migration cutover has completed and the old store is read-only; a bug
  in the new service is discovered. Deploy a fix to the new service.
- An API migration has removed the old endpoint; a consumer reports a
  regression. Fix the new endpoint.
- A configuration error in the new infrastructure is causing errors. Correct
  the configuration and redeploy.

**Anti-patterns:**
- Using roll-forward as the default recovery path without assessing whether
  rollback is simpler and safer.
- Failing to define the acceptable fix-forward window (how long can the system
  be degraded before the fix lands?).

### Restore

Restore the prior state from a backup or snapshot.

**Decision rule:** Restore is the path when the old system is no longer
operational but a backup exists and a restore procedure is tested and has a
known recovery time.

**Examples:**
- A schema migration dropped the wrong table; restore from the pre-migration
  backup.
- A data migration corrupted the target store; restore the target from the
  pre-migration snapshot and re-run the migration.
- An infrastructure migration destroyed the old environment; restore from the
  infrastructure-as-code state and redeploy.

**Anti-patterns:**
- Assuming restore is possible because "we have backups." A backup that has not
  been tested with a restore drill is not a recovery path — it is a hope.
- Failing to define the Recovery Time Objective (RTO) and Recovery Point
  Objective (RPO) for the restore.

### Irreversible

Reversal is impossible. The change cannot be undone at any level.

**Decision rule:** Irreversible when (a) the old state is physically destroyed,
(b) the operation is one-way by design (e.g., cryptographic erasure), or (c) a
third-party action cannot be recalled.

**Examples:**
- Physical hardware decommissioning where the device is shipped back and
  wiped.
- Cryptographic key rotation where old keys are destroyed after rotation.
- Third-party data export where the receiving party cannot be compelled to
  delete the data.
- Permanent data deletion to satisfy a regulatory requirement (e.g., GDPR
  right-to-erasure).

**Required for every irreversible step:**
1. **Acceptance criteria** — what conditions must be met before the
   irreversible step is executed (e.g., "reconciliation passed at 100% for 7
   consecutive days").
2. **Stakeholder communication** — who must be informed and who must approve
   before the step executes.
3. **Contingency plan** — what happens if the irreversible step succeeds but
   the overall migration subsequently fails (e.g., "rebuild from source of
   truth," "accept data loss within defined scope").

**Anti-patterns:**
- Treating an irreversible step as if it were reversible — stating "rollback:
  N/A" without the acceptance, communication, and contingency requirements.
- Claiming "irreversible" for a step that is merely expensive or inconvenient to
  reverse. Irreversible means physically or logically impossible, not merely
  costly.

## Classification decision tree

```
Can the old state be reactivated without data loss?
  ├── YES → Rollback is possible
  └── NO:
      ├── Can the new state be fixed within the acceptable recovery window?
      │   └── YES → Roll-forward is possible
      └── Can the old state be restored from backup?
          ├── YES, and restore procedure is tested → Restore is possible
          └── NO → Irreversible
```

## When not to claim rollback

Never claim rollback is possible when:
- The old system has been decommissioned and cannot be restarted.
- The old data has been deleted and no backup exists.
- The old API has been removed and cannot be redeployed.
- A third-party action cannot be reversed.
- The rollback procedure has never been tested.

In these cases, classify as roll-forward, restore, or irreversible — not as
rollback with caveats.