Rollback First Planning
If you cannot describe how to undo a change in one exact command, you are not ready to make it. Decide the undo, prove it works, then apply.
Procedure
- Classify the change: local file (cheap undo), database (needs snapshot), deployed service (needs prior version), or external side effect (email, published package, payment — often irreversible).
- For file and config changes, take a timestamped copy before editing:
cp config/app.yaml config/app.yaml.$(date +%Y%m%dT%H%M%S).bak.
- For database work, snapshot first:
pg_dump -Fc dbname > /tmp/dbname.dump or sqlite3 app.db ".backup '/tmp/app.db.bak'". Verify the dump is non-empty: ls -l /tmp/dbname.dump.
- For a deployed service, record the current artifact identity: the image digest (
docker inspect --format='{{.RepoDigests}}' <container>), the git tag, or the release id. Rollback is redeploy of that exact identity.
- Write the rollback command into the plan file beside the forward command. Both must be one-liners you can paste.
- Prove the undo works on a copy or in a scratch directory before touching the real target. Do not "trust" a backup you never restored.
- Enumerate external side effects explicitly. For anything that cannot be undone (a sent email, a pushed tag, a minted token), mark it
IRREVERSIBLE and require a gate as in irreversible-action-gate.
- Only after steps 1-7, execute the forward change.
- After success, keep the backup until verification passes; delete it only when the change is confirmed good.
- Name the trigger that would force the rollback ("error rate over 1% for 5 minutes") so the decision is not made under pressure.
- Store the rollback command in the plan file, not in your head, so another actor can execute it.
- After applying, record the forward-change timestamp and the current good version so "roll back to" is unambiguous.
Pitfalls
- A backup produced by
mv of the original, so "restore" just moves the broken file back.
- Rolling back code but not the schema migration that shipped with it.
- Assuming
git revert undoes a deploy — it does not redeploy anything.
- Deleting the backup in the same script that makes the change, before the change is verified.
- Forgetting a side effect: a cron job edited, a webhook fired, a cache warmed with the new values.
- A rollback plan that requires the very service that is down in order to run.
- Rolling back the deploy but leaving the config change that accompanied it in place.
Verification
ls -l config/app.yaml.*.bak /tmp/dbname.dump
# passes when the pre-change copies exist and are non-empty
Report to the user: the forward command, the rollback command, and whether the rollback was tested on a copy or only reasoned about.
1---2name: rollback-first-planning3description: Use when about to change live, shared, or hard-to-recreate state. Requires a tested undo path to exist before the change is attempted.4metadata:5 source: https://skillmd.com/skills/jiayaoqijia/rollback-first-planning6---78# Rollback First Planning910If you cannot describe how to undo a change in one exact command, you are not ready to make it. Decide the undo, prove it works, then apply.1112## Procedure13141. Classify the change: local file (cheap undo), database (needs snapshot), deployed service (needs prior version), or external side effect (email, published package, payment — often irreversible).152. For file and config changes, take a timestamped copy before editing:16 `cp config/app.yaml config/app.yaml.$(date +%Y%m%dT%H%M%S).bak`.173. For database work, snapshot first: `pg_dump -Fc dbname > /tmp/dbname.dump` or `sqlite3 app.db ".backup '/tmp/app.db.bak'"`. Verify the dump is non-empty: `ls -l /tmp/dbname.dump`.184. For a deployed service, record the current artifact identity: the image digest (`docker inspect --format='{{.RepoDigests}}' <container>`), the git tag, or the release id. Rollback is redeploy of that exact identity.195. Write the rollback command into the plan file beside the forward command. Both must be one-liners you can paste.206. Prove the undo works on a copy or in a scratch directory before touching the real target. Do not "trust" a backup you never restored.217. Enumerate external side effects explicitly. For anything that cannot be undone (a sent email, a pushed tag, a minted token), mark it `IRREVERSIBLE` and require a gate as in `irreversible-action-gate`.228. Only after steps 1-7, execute the forward change.239. After success, keep the backup until verification passes; delete it only when the change is confirmed good.2410. Name the trigger that would force the rollback ("error rate over 1% for 5 minutes") so the decision is not made under pressure.2511. Store the rollback command in the plan file, not in your head, so another actor can execute it.2612. After applying, record the forward-change timestamp and the current good version so "roll back to" is unambiguous.2728## Pitfalls2930- A backup produced by `mv` of the original, so "restore" just moves the broken file back.31- Rolling back code but not the schema migration that shipped with it.32- Assuming `git revert` undoes a deploy — it does not redeploy anything.33- Deleting the backup in the same script that makes the change, before the change is verified.34- Forgetting a side effect: a cron job edited, a webhook fired, a cache warmed with the new values.35- A rollback plan that requires the very service that is down in order to run.36- Rolling back the deploy but leaving the config change that accompanied it in place.3738## Verification3940 ls -l config/app.yaml.*.bak /tmp/dbname.dump41 # passes when the pre-change copies exist and are non-empty4243Report to the user: the forward command, the rollback command, and whether the rollback was tested on a copy or only reasoned about.