BMAD-METHOD/src/modules/bmm-release/workflows/rollback-planning/instructions.md

Rollback Planning Instructions

Objective

Create a comprehensive rollback plan for a release, ensuring quick recovery if deployment issues occur.

Prerequisites

• Release candidate or deployed release identified
• Previous stable version available
• Understanding of data migration impacts

---

Identify Release and Target

Load release history from state

What is the context for this rollback plan? [p] Pre-deployment - Planning ahead for new release [a] Active issue - Need to rollback now [r] Review - Updating existing rollback plan

Context:

Store as {{rollback_context}}

**URGENT MODE ACTIVATED** Load current deployed version Identify last known good version Skip optional steps, focus on execution

---

Version Selection

Current Version: {{current_version}}

Available Rollback Targets:

Version	Deployed	Status	Age
{{#each available_versions}}
{{version}}	{{deployed_date}}	{{status}}	{{age}}
{{/each}}

Which version should we rollback to? (Enter version number or select from list):

Store as {{target_version}} Validate target version exists and is stable

Rollback Path: {{current_version}} → {{target_version}}

---

Impact Analysis

Load changes between versions Identify database migrations Check for breaking changes

Changes to Revert:

• Stories: {{stories_between_versions.length}}
• Database migrations: {{migrations.length}}
• API changes: {{api_changes.length}}
• Configuration changes: {{config_changes.length}}

{{#if migrations.length}} Database Migrations:

Migration	Type	Reversible
{{#each migrations}}
{{name}}	{{type}}	{{reversible ? 'Yes' : 'NO'}}
{{/each}}

**WARNING:** Some migrations are not reversible. Manual intervention required. {{/if}}

{{#if breaking_changes}} Breaking Changes to Consider: {{#each breaking_changes}}

• {{description}} {{/each}} {{/if}}

---

Rollback Procedure

Generate rollback steps based on deployment type

Pre-Rollback Checklist:

• Notify stakeholders of planned rollback
• Ensure target version artifacts are available
• Verify database backup exists
• Confirm rollback team is available
• Document current error/issue being resolved

Rollback Steps:

1. Announce Maintenance

   • Notify users of planned maintenance
   • Enable maintenance mode if available

2. Stop Traffic

   • Route traffic away from affected services
   • Drain existing connections

3. Database Rollback {{#if migrations.length}}(if needed){{/if}} {{#each migrations_to_revert}}

   • Revert: {{name}}

     {{down_script}}
     

{{/each}}

4. Deploy Previous Version

   • Target version: {{target_version}}
   • Deployment command: {{deploy_command}}

5. Verify Deployment

   • Run health checks
   • Verify critical endpoints
   • Check error rates

6. Restore Traffic

   • Re-enable traffic routing
   • Monitor for issues

7. Post-Rollback

   • Disable maintenance mode
   • Notify stakeholders
   • Document rollback reason

---

Verification Checklist

What are the critical checks after rollback? (Enter comma-separated or press Enter for defaults):

Health Checks:

• Service responds to health endpoint
• Database connectivity verified
• Cache connectivity verified
• External service integrations working

Functional Checks:

• User authentication works
• Core workflows functional
• Critical API endpoints responding
• No elevated error rates

Performance Checks:

• Response times within SLA
• No memory leaks
• CPU utilization normal

---

Escalation Procedures

Define escalation contacts for rollback issues:

Level 1 (On-call): Level 2 (Engineering Lead): Level 3 (VP/Director):

Enter contacts:

Escalation Matrix:

Issue	Contact	Response Time
Rollback fails	{{level_1}}	Immediate
Data inconsistency	{{level_2}}	15 minutes
Extended outage	{{level_3}}	30 minutes

---

Generate Rollback Plan

# Rollback Plan: {{current_version}} → {{target_version}}

Created: {{date}} Context: {{rollback_context}} Estimated Duration: {{estimated_duration}}

Summary

• Current Version: {{current_version}}
• Target Version: {{target_version}}
• Stories Affected: {{stories_between_versions.length}}
• Database Changes: {{migrations.length}}

Pre-Rollback Checklist

{{pre_rollback_checklist}}

Rollback Steps

{{rollback_steps}}

Verification Checklist

{{verification_checklist}}

Escalation Contacts

{{escalation_matrix}}

Rollback Command

{{rollback_command}}

---

Plan generated by BMAD Release Manager

---

Save Plan

Save rollback plan to output file Link plan to release candidate Update state with rollback plan reference

Plan Saved: {{output_file_path}}

---

Completion

Rollback plan created for {{current_version}} → {{target_version}}.

Summary:

• Estimated Duration: {{estimated_duration}}
• Database Migrations: {{migrations.length}}
• Manual Steps Required: {{manual_steps_count}}

Plan Location: {{output_file_path}}

## EXECUTE ROLLBACK NOW?

Ready to execute rollback? [y] Yes - execute rollback procedure [n] No - save plan for later

Choice:

Execute rollback procedure {{release_id}} {{current_version}} {{target_version}} {{environment}} {{user_name}} {{rollback_reason}} {{current_timestamp}}