rollback-readiness

---
name: rollback-readiness
description: Review, design, and implement rollback-ready software changes. Use for PRs, deploy plans, migrations, feature flags, API changes, refactors, incident fixes, and production risk reviews.
license: MIT
---

# Rollback Readiness

## Overview

Use this skill to make speed safe. Treat rollback as part of the design of a change, not as an afterthought after deploy.

Prioritize practical engineering controls: small PRs, feature flags, reversible migrations, gradual rollout, compatibility windows, observability, and explicit human gates for risky changes.

## When Not To Use

Skip this skill when the work is clearly low-risk:

- Typo, formatting, or comment-only edits.
- Documentation-only changes with no customer, deploy, or operational impact.
- Small tests or local developer tooling that do not affect CI/CD behavior.
- Purely internal refactors that are narrow, well-tested, and not user-visible.
- Exploratory debugging before there is a proposed deployable change.

For low-risk work, keep the rollback note lightweight: "Rollback: revert the commit." Do not add process overhead that would slow down a safe, obvious fix.

## Workflow

1. Classify the change.
   - Feature behavior
   - Database migration or data backfill
   - External API or contract change
   - Refactor
   - Config, permissions, or infrastructure
   - Background job, queue, or scheduled task
   - AI-generated or AI-modified code across several files

2. Map blast radius.
   - Identify affected users, services, jobs, tables, endpoints, queues, caches, dashboards, and teams.
   - Mark whether the change is user-visible, data-destructive, contract-breaking, or hard to observe.
   - Treat broad AI-generated changes as higher risk unless the PR is small and well tested.

3. Check rollback paths before approving deploy.
   - Can the change be disabled with a feature flag or config switch?
   - Can the deploy be reverted without breaking database compatibility?
   - Are migrations reversible or at least forward-compatible?
   - Can old and new code run together during rollout?
   - Can the change be deployed to a subset of users, tenants, traffic, or workers?
   - If rollback is unsafe, is there a clear roll-forward or mitigation path?

4. Check PR shape.
   - Prefer one behavior change per PR.
   - Split refactors from functional changes.
   - Split schema changes from code paths when needed.
   - Avoid AI-generated PRs that touch many layers without a clear reason.
   - Ask for a smaller PR when review quality drops.

5. Require verification and signals.
   - Identify the minimum tests needed before merge.
   - Identify the metric, log, trace, alert, or query to watch after deploy.
   - Define what counts as a failed rollout.
   - Define who can pause, disable, revert, or continue rollout.

6. Handle missing context explicitly.
   - If the rollback path, deploy plan, migration safety, flag behavior, or monitoring is unclear, list it under `Unknowns`.
   - Do not assume a change is safe when the diff or plan does not show the control.
   - Ask only for missing information that changes the deploy decision.

7. Produce a clear decision.
   - `Ready`: safe enough to deploy with named rollback path and monitoring.
   - `Ready with conditions`: deploy only after specific fixes or checks.
   - `Split first`: PR is too broad or mixes risk types.
   - `Do not deploy`: rollback path is missing for a risky change.

## Resolving Issues

When the user asks to resolve an issue, bug report, incident follow-up, or ticket, use rollback readiness as part of the implementation path, not only as a final review.

First decide whether the issue needs this skill. Use it when the issue touches production behavior, user-visible flows, persistent data, external integrations, jobs, queues, permissions, infrastructure, deploy pipelines, or broad AI-generated changes. Skip it for narrow local fixes with no meaningful deploy risk.

1. Restate the issue as a deployable change.
   - Identify the failing behavior, affected surface, likely blast radius, and expected user-visible result.
   - Separate diagnosis, fix, migration, config, and cleanup work when they carry different rollback risks.

2. Prefer the smallest safe fix.
   - Fix the failure-prone path before broad refactors.
   - Keep unrelated cleanup out of the issue unless it materially reduces rollback risk.
   - Put risky or user-visible behavior behind a flag, config switch, cohort, or kill switch when practical.

3. Preserve compatibility.
   - Keep old and new code, data, API payloads, job payloads, and config values compatible across the deploy window.
   - If compatibility cannot be preserved, document the mitigation or roll-forward path before implementing.

4. Verify the issue is actually resolved.
   - Add or run the smallest test that would fail before the fix.
   - Include a runtime signal to watch after deploy when tests cannot fully cover the failure mode.
   - Define the rollback trigger: the metric, error, log, or user report that means stop rollout.

5. Return implementation-ready output.
   - For code work: summarize the fix, tests run, rollback path, post-deploy signal, and residual risk.
   - For planning work: produce ordered issues or PR slices with verification and rollback criteria for each slice.

For issue execution, prefer this final shape:

```text
Issue decision: Ready with conditions

Fix summary:
- Implement the smallest change that resolves the failing behavior.

Verification:
- Test or reproduction that would fail before the fix and pass after it.

Rollback:
- Disable flag/config, revert commit, pause worker, restore previous value, or use the named mitigation.

Post-deploy signal:
- Metric, log, trace, alert, queue depth, reconciliation query, or user report to watch.

Residual risk:
- Known gap, assumption, or reason the rollback is limited.
```

## Review Output

When reviewing a PR, diff, release plan, or migration, lead with issues in severity order:

```text
Decision: Ready with conditions

Findings:
- [P1] Migration drops data before the new code has fully rolled out.
- [P2] Feature has no flag, so rollback requires a full redeploy.

Required before deploy:
- Add expand-and-contract migration plan.
- Put the new behavior behind a feature flag.
- Add a dashboard or query for failed requests.

Unknowns:
- Whether old and new app versions run at the same time during deploy.

Assumptions:
- Workers drain before the app deploy is reverted.

Rollback path:
- Disable flag `new_checkout_flow`.
- Keep old column readable for one release.
- Revert app deploy only after traffic drains from workers.

Roll-forward path:
- Restore writes to both columns and resume the backfill from the last checkpoint.
```

Use these severities:

- `P0`: Do not deploy; the change can cause irreversible data loss, security exposure, or broad outage.
- `P1`: Must fix before deploy; rollback or detection is too weak for the risk.
- `P2`: Deploy only with conditions; risk is manageable after specific checks or controls.
- `P3`: Improvement; useful hardening that should not block a low-risk deploy.

When designing a new implementation, output a deployment-safe plan:

```text
Plan:
1. Add backward-compatible schema.
2. Deploy code that writes both old and new fields.
3. Backfill in batches.
4. Enable reads through a feature flag.
5. Monitor errors and data drift.
6. Remove old path in a later PR.
```

When breaking work into issues, make each issue independently deployable:

```text
Issue: Add dual-write support for order totals

Goal:
- Write both old and new totals without changing reads.

Acceptance:
- Existing reads keep using `orders.total`.
- New writes populate `orders.total_v2`.
- Unit test covers both write paths.

Rollback:
- Disable dual-write config and keep reads on `orders.total`.

Signal:
- Compare old and new totals for drift after deploy.
```

## High-Risk Signals

Pause and call out risk when any of these appear:

- Destructive migration without backup, batch plan, or compatibility window.
- API contract change without versioning, fallback, or client migration plan.
- Feature rollout with no flag, kill switch, or scoped enablement.
- Large AI-generated PR mixing refactor, behavior, schema, and tests.
- Background job change that can duplicate, skip, or corrupt work.
- Permission or security change that cannot be quickly reversed.
- Missing observability for user-facing or revenue-impacting behavior.
- Rollback requires manual data repair, vendor action, or client coordination that is not planned.

## Reference

Read `references/rollback-patterns.md` when the task involves migrations, feature flags, deploy strategy, PR splitting, background jobs, queues, config, infrastructure, permission changes, observability, or a detailed rollback checklist.