Rollback planning

Rollback Planning

Use this skill when reverting, rolling back, or falling back may be safer than pushing forward.

Goal

Increase recovery success rate by answering these questions before acting:

1. what exactly would be rolled back
2. what can be reversed safely
3. what cannot be reversed cleanly
4. what the rollback trigger should be
5. what order of operations is safest
6. what evidence confirms rollback success

Core Rules

1. Define the rollback unit clearly

Before planning rollback, restate the unit:

• code change
• branch or commit range
• config change
• deployment artifact
• generated data or migration effect
• user-visible feature flag or route behavior

If the rollback unit is unclear, the rollback itself is risky.

2. Separate reversible from irreversible changes

Not everything can be cleanly rolled back.

Classify changes such as:

• code and config changes
• schema or migration changes
• generated files or cached artifacts
• external side effects
• user data changes
• one-way integrations or notifications already sent

A rollback plan must state what can be reversed and what requires mitigation instead.

3. Prefer rollback criteria over panic

Do not rollback just because something feels wrong.

Define triggers such as:

• severity threshold
• blast radius threshold
• failed health/validation checks
• inability to stabilize with a hotfix
• unacceptable correctness, availability, or performance regression

4. Sequence the rollback safely

Prefer the smallest rollback that reduces impact fastest.

Plan the order explicitly:

• what to stop or disable first
• what to revert next
• what to verify immediately after
• what to communicate or document after rollback

5. Preserve evidence before changing the scene

Before rollback, capture the minimum evidence needed for later debugging:

• symptom summary
• affected scope
• current version/commit/config state
• recent trigger or release association
• current logs/errors if relevant

Do not erase the incident picture before preserving enough context.

6. Verify rollback success explicitly

Rollback is not complete just because the previous version was restored.

Confirm:

• the bad symptom is gone or reduced
• the intended fallback path works
• no new incident was introduced
• the remaining caveats are known

Minis-Specific Workflow

Shell-first rollback checks

Use shell commands to:

• inspect current branch/commit/diff state
• identify recent releases or changes
• compare current and last-known-good state
• verify which files/config changed
• confirm the rollback target exists and is well understood

Browser-assisted rollback verification

For web incidents:

• confirm whether the user-visible symptom disappears after rollback
• verify fallback route/page behavior
• confirm the rollback did not introduce a different visible failure

Smallest-safe-reversal bias

On Minis, prefer rollback plans that are:

• explicit
• narrow in scope
• easy to verify
• reversible again if needed

Avoid broad, unclear reversions under pressure.

Rollback Planning Sequence

Use this order:

1. Restate the incident/change and rollback target.
2. Identify rollback trigger and urgency.
3. Classify reversible vs irreversible effects.
4. Choose the smallest effective rollback scope.
5. Define rollback steps in order.
6. Define immediate verification checks.
7. List remaining caveats and follow-up debugging path.

Common Rollback Failures

Watch for:

• rolling back too broadly when a narrower containment option exists
• reverting code but not config or assets
• ignoring one-way side effects already emitted
• losing useful evidence before rollback
• not verifying the rollback actually fixed user impact
• introducing a second problem while undoing the first
• no clear last-known-good reference

Integration with Other Skills

• Use incident-triage first to assess severity, blast radius, and whether rollback is actually the right next step.
• Use deployment-verification to confirm the rollback target or fallback path behaves correctly in the target-like environment.
• Use release-readiness later if the reverted or replacement state needs a new go/no-go judgment.
• Use root-cause-tracing after stabilization if deeper debugging is still needed.
• Use agent-security-guard if rollback involves production actions, secrets, or risky system changes.

Completion Checklist

Before calling the rollback plan ready, check:

• Is the rollback target clearly identified?
• Are rollback triggers explicit?
• Are reversible vs irreversible effects separated?
• Is the rollback scope as small as practical?
• Are verification steps clear?
• Are remaining caveats and follow-up steps documented?

Response Template

• Rollback target:
• Rollback trigger:
• Reversible effects:
• Irreversible or mitigation-needed effects:
• Rollback steps:
• Verification checks:
• Remaining caveats:
• Suggested next step:

Example Triggers

• "If we need to rollback, what is the safest plan?"
• "Help me decide the smallest rollback that reduces impact."
• "Plan a rollback for this release without making things worse."
• "Which parts of this change are reversible vs irreversible?"
• "Define rollback criteria and verification steps for this incident."