Deploy Rollback Skill

Emergency rollback to a previous deployment version with verification and incident reporting.

Overview

Trigger: /popkit-ops:deploy rollback or when a deployment fails

Purpose: Safely revert a deployment to the last known good version. Validates rollback success and generates an incident report for post-mortem analysis.

Critical Rules

1. ALWAYS assess before rolling back - Understand what failed and why
2. ALWAYS confirm before executing rollback - Require explicit user confirmation
3. ALWAYS verify after rollback - Confirm the rollback was successful
4. ALWAYS record rollback in history - Update deploy.json with rollback status
5. RECOMMEND incident report - Always offer to create one after rollback

Required Decision Points

Step	When	Decision ID
1	Strategy selection	rollback_strategy
2	Before execution	confirm_rollback
3	After rollback	incident_report

Skipping these violates PopKit UX standard.

Process

Step 1: Assess Situation

python scripts/rollback_deployment.py --dir . --action assess --target docker

This:

• Loads deploy.json and deployment history
• Identifies current deployed version
• Finds last successful deployment (rollback target)
• Assesses impact and risk

Step 2: Rollback Strategy (MANDATORY)

Use AskUserQuestion:
- question: "How should I roll back?"
- header: "Strategy"
- options:
  - "Previous version (Recommended)" - Last successful deployment
  - "Specific version" - Choose a specific version
  - "Investigate first" - Gather more info

Step 3: Confirm Rollback (MANDATORY)

Use AskUserQuestion:
- question: "Confirm rollback? This will revert the deployment."
- header: "Confirm"
- options:
  - "Roll back now" - Execute immediately
  - "Dry run first" - Simulate the rollback
  - "Abort" - Cancel rollback

Step 4: Execute Rollback

python scripts/rollback_deployment.py --dir . --action rollback --target docker --version 1.1.0

Step 5: Verify

python scripts/rollback_deployment.py --dir . --action verify --target docker

Step 6: Incident Report (MANDATORY)

Use AskUserQuestion:
- question: "Rollback complete. Create incident report?"
- header: "Report"
- options:
  - "Create report (Recommended)" - Generate for post-mortem
  - "Skip report" - No report needed

Rollback Strategies

Docker Rollback

1. Pull previous image tag from registry
2. Stop current container(s)
3. Start container(s) with previous image
4. Verify health checks pass

npm Rollback

1. Deprecate failed version
2. Point latest dist-tag to previous version
3. Publish notice if public package

Kubernetes Rollback

1. Use kubectl rollout undo for deployments
2. Verify pod health
3. Check service endpoints

Platform Rollback (Vercel/Netlify)

1. Promote previous deployment to production
2. Verify domain routes correctly

Output Format

Deployment Rollback
===================
Target: docker
Current: 1.2.0 (FAILED)
Rollback to: 1.1.0 (last successful)

Steps:
  [1/4] Pulling previous image... done
  [2/4] Stopping current... done
  [3/4] Starting rollback version... done
  [4/4] Health check... passed

Result: ROLLBACK SUCCESS
Duration: 25s

Incident Report: .claude/popkit/incidents/incident-20260318-143500.md
Next: Investigate root cause, then /popkit-ops:deploy execute when fixed

Incident Report Format

Generated at .claude/popkit/incidents/incident-{timestamp}.md:

# Deployment Incident Report

## Summary

- **Date:** 2026-03-18T14:35:00Z
- **Target:** docker
- **Failed Version:** 1.2.0
- **Rolled Back To:** 1.1.0
- **Duration of Outage:** ~5 minutes
- **Severity:** P2

## Timeline

- 14:30:00 - Deployment of v1.2.0 initiated
- 14:30:45 - Deployment completed
- 14:31:00 - Health check failures detected
- 14:33:00 - Rollback initiated
- 14:35:00 - Rollback completed, service restored

## Root Cause

[To be filled during post-mortem]

## Impact

[To be filled during post-mortem]

## Action Items

- [ ] Investigate root cause
- [ ] Add regression test
- [ ] Update deployment validation checks

Integration

Called by:

• /popkit-ops:deploy rollback command
• pop-deploy-execute workflow (on failure)
• rollback-specialist agent

Triggers:

• rollback-specialist agent

Followed by:

• pop-deploy-validate - Re-validate after fixing issues
• pop-deploy-execute - Re-deploy when fixed

Related

Component	Relationship
pop-deploy-execute	Deployment that may need rollback
pop-deploy-validate	Post-rollback validation
rollback-specialist	Agent for rollback operations
deploy.json	Configuration and history