Rollback plan template | Brightfield Works

Take it, fork it, rename it. The template is deliberately short: five required sections and two optional sections for time budget and known gotchas.

<!--
  Rollback plan - template
  Brightfield Works · public domain (CC0). Take it, fork it, rename it.
  Source: https://www.brightfieldworks.com/insights/write-the-rollback-plan-first/
  v 1.0
-->

# Rollback plan - `<change name>`

> Write this *before* the change procedure, not after. If a section is hard to fill
> in, that is the section telling you something. Keep every answer as short as it
> can honestly be.

**Change:** `<one line: what is being changed, and to what>`
**Owner:** `<name>`
**Date:** `<YYYY · MM · DD>`
**Status:** draft / reviewed / live

---

## 01 · Trigger conditions

*The specific, observable conditions under which we invoke rollback. Not "something
seems off", conditions you could write a monitoring check against.*

- `<condition - e.g. error rate on X exceeds N for M minutes>`
- `<condition - e.g. downstream service Y fails health check after cutover>`
- `<condition - e.g. validation/auth failures reported by Z>`

## 02 · Decision authority

*Who calls it, who is consulted, who is told. By name and by role, with a backup
for each. Settle the ambiguity now, not during the incident it describes.*

| Role | Person | Backup |
|------|--------|--------|
| Calls rollback | `<name>` | `<name>` |
| Consulted | `<name>` | `<name>` |
| Informed | `<name / list>` | - |

## 03 · Procedure

*The steps to put the previous state back, with the actual commands, in order.
Tested where the test is cheap. Read by a second pair of eyes who did not write it.*

1. `<step - command or action>`
2. `<step - command or action>`
3. `<step - command or action>`

**Verification:** `<how we confirm the rollback worked - the check, not the hope>`

## 04 · Data implications

*What is lost, what is reconciled, and how, including the honest case where some
data cannot be recovered, and what we do then.*

- **Changed since cutover:** `<what data has accumulated, and where>`
- **Reconciliation:** `<how it is merged back, by whom, manual or automated>`
- **Unrecoverable:** `<what cannot be rolled back, and the plan for that case>`

## 05 · Communication

*What is said, to whom, through which channel. Pre-written if the change is visible
to end users.*

- **Internal:** `<channel · who posts · what>`
- **Affected users:** `<channel · who posts · pre-written message below>`

> `<pre-written user-facing message, if applicable>`

---

## 06 · Time budget *(optional, but usually worth it)*

*The crossover point: the time, or the volume of accumulated data, past which
rollback is no longer cheaper than fixing forward. Decide it in daylight.*

- **Rollback is the cheaper option until:** `<time / data threshold>`
- **After that point, we:** `<fix forward / escalate / hold>`

## 07 · Known gotchas *(optional)*

*One-way doors, things that age out, downstream systems that cache state, anything
that bit you last time.*

- `<gotcha>`
- `<gotcha>`

---

*Brightfield Works · "A working rollback plan is the cheapest insurance you can write."*
*Public domain (CC0). v 1.0*

Cookies & analytics