← All craftbooks

Rollback Plan

Ship and releaseevalv1.0.0released 2026-06-05workflow: build-loop

Steps

Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.

1. Scope failure modes and triggersplannerentry

   define what 'roll back' means and when to pull the trigger

   Show working prompt

   1. Identify the change being deployed (service, version, what it touches) and enumerate the realistic failure modes: error-rate spike, latency regression, broken migration, data corruption, dependency outage, bad feature flag. 2. For each failure mode define the TRIGGER — the objective signal and threshold that means 'roll back now' (e.g. '5xx > 2% for 5 min', 'p99 latency doubles', 'data-integrity check fails'). 3. Decide the rollback STRATEGY per failure mode: redeploy previous artifact, flip a feature flag, run a down-migration, restore from backup — and flag which changes are NOT cleanly reversible (irreversible migrations, deleted data, externally-visible side effects). 4. Identify who decides and who executes, and the target recovery-time objective. 5. Good looks like: a list of failure modes each with a measurable trigger and a chosen reversal strategy, with irreversible hazards called out explicitly. Write this as an acceptance-criteria checklist ('every failure mode has a measurable trigger', 'every reversible change has a reversal step', 'irreversible hazards are flagged with mitigation', 'RTO and decision owner stated') plus the analysis to the notes file via write_task_note AND to notes/scope.md.

2. Write the rollback runbookdeveloper

   produce precise, ordered reversal steps with real commands

   Show working prompt

   1. Open notes/scope.md and write the rollback runbook as a numbered, copy-pasteable procedure an on-call engineer can follow at 3am under stress. 2. Structure it: Trigger conditions (from scope) → Pre-rollback safety checks (snapshot/backup, announce, freeze) → Reversal steps in exact order with the real command or action for each → Data-handling steps (down-migrations, and explicit handling for any irreversible change) → Post-rollback verification (the checks that confirm the system is healthy again) → Communication/escalation. 3. For each reversal step give the concrete command/UI action and the expected result, so there is zero improvisation. 4. Call out every irreversible step with its mitigation (e.g. 'this migration drops a column — take a backup first; restoring requires X'). 5. State the expected recovery time. 6. Good looks like: a self-contained runbook where every reversible change from scope.md has an ordered step with a real command, every irreversible hazard has a mitigation, and a verification step confirms recovery. Write the runbook to rollback-plan.md.

3. Dry-run and reviewreviewer

   trace the steps for correctness and data hazards

   Show working prompt

   1. Open rollback-plan.md and mentally (or actually, in a safe environment) dry-run each reversal step in order — does it run, is it in the right sequence, does it actually undo the change? 2. Confirm every failure mode and trigger from notes/scope.md is covered and that each reversible change has a working reversal step. 3. Scrutinize the irreversible/data-loss steps hardest: is the hazard flagged, is the mitigation real and ordered BEFORE the destructive action? 4. Verify the post-rollback verification genuinely proves health, not just that a command exited 0. 5. Write a PASS/FAIL per acceptance criterion and list any gap, wrong ordering, or unguarded destructive step. 6. Any failure routes back to the write phase. Write findings to notes/review.md.

4. Evaluatereviewer

   Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

   Show working prompt

   Open rollback-plan.md and verify it against notes/scope.md, PASS/FAIL each criterion. Confirm: (a) every failure mode has a measurable trigger condition; (b) every reversible change has an ordered, concrete reversal step with a real command; (c) every irreversible/data-loss hazard is flagged with a mitigation that happens BEFORE the destructive action; (d) pre-rollback safety checks and a post-rollback verification that proves health are present; (e) an RTO and a decision owner/escalation path are stated; (f) the steps read as a runbook executable under pressure with no improvisation. Any FAIL routes back to the write phase.
   
   Then route — this is the whole point of the loop:
   
   - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
   - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "write" })` to loop back. The builder fixes exactly those gaps.
   
   Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.

5. Finishdeveloper

   All acceptance criteria met. Stamp a short summary and report DONE.

   Show working prompt

   Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

• write a rollback plan
• how do we roll back this release
• revert plan for deploy
• rollback runbook
• undo the deploy safely

Source

View this craftbook on GitHub · MIT license