@cloudkinetix/bmad-enhanced/expansion-packs/ck-parallel-dev/templates/rollback-guide-tmpl.md

Cloud-Kinetix enhanced fork of BMAD-METHOD - Breakthrough Method of Agile AI-driven Development with robust versioning and unified validation.

# Rollback Guide - Run {{run-id}}

[[LLM: Default path: .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/rollback-guide.md]]

[[LLM: This guide documents how to safely rollback changes from this parallel-dev run. Generate alongside pre-execution report for audit trail.]]

## Quick Rollback

**Run ID**: {{run-id}}  
**Executed**: {{execution timestamp}}  
**Status**: {{COMPLETED|PARTIAL|FAILED}}  
**Rollback Complexity**: {{LOW|MEDIUM|HIGH}}  
**Automated Rollback Available**: {{Yes|Partial|No}}

### Immediate Actions

If you need to rollback immediately:

```bash
# Quick rollback command (if automated rollback available)
cd {{project_root}}
./rollback-parallel-dev.sh {{run-id}}

# OR Manual rollback (always works)
{{List specific commands based on execution state}}
```

## Execution Summary

### Work Items Executed

| Worktree | Branch           | Status        | Commits    | Can Rollback |
| -------- | ---------------- | ------------- | ---------- | ------------ | --------- | ----- | -------- |
| {{wt1}}  | parallel/{{wt1}} | {{✅ Complete | ⚠️ Partial | ❌ Failed}}  | {{count}} | {{Yes | Manual}} |
| {{wt2}}  | parallel/{{wt2}} | {{✅ Complete | ⚠️ Partial | ❌ Failed}}  | {{count}} | {{Yes | Manual}} |

### Current State

```bash
# Check current state
git worktree list
git branch -a | grep parallel/

# Main branch status
git status
git log --oneline -10
```

## Rollback Strategies

### Strategy 1: Complete Automated Rollback ({{Available|Not Available}})

[[LLM: Only if all conditions met: clean worktrees, no manual changes, all tracked]]

```bash
#!/bin/bash
# Automated rollback script

echo "Rolling back parallel-dev run {{run-id}}"

# Step 1: Verify state
if [[ $(git status --porcelain) ]]; then
    echo "ERROR: Working tree not clean. Commit or stash changes first."
    exit 1
fi

# Step 2: Remove worktrees
{{for each worktree}}
git worktree remove ../{{worktree}} --force

# Step 3: Delete branches
{{for each branch}}
git branch -D parallel/{{branch}}

# Step 4: Reset main if merged
{{if changes were merged to main}}
git reset --hard {{commit-before-merge}}

echo "Rollback complete. State restored to before run {{run-id}}"
```

### Strategy 2: Selective Rollback (Recommended for Partial Success)

When some work items succeeded and others failed:

#### Keep Successful Work

```bash
# Merge only successful branches
git merge parallel/{{successful-branch-1}}
git merge parallel/{{successful-branch-2}}

# Remove failed work
git worktree remove ../{{failed-worktree}}
git branch -D parallel/{{failed-branch}}
```

#### Rollback Specific Work Item

```bash
# To rollback just one work item
cd ../{{worktree}}
git log --oneline  # Note commits to revert

cd {{main-project}}
git revert {{commit-hash-1}} {{commit-hash-2}}
```

### Strategy 3: Manual Step-by-Step Rollback

For complex situations or when automated rollback isn't safe:

#### Step 1: Document Current State

```bash
# Save current state for reference
git worktree list > rollback-state-{{timestamp}}.txt
git branch -a >> rollback-state-{{timestamp}}.txt
git log --oneline -20 >> rollback-state-{{timestamp}}.txt
```

#### Step 2: Clean Up Worktrees

```bash
# For each worktree, check and remove
cd ../{{worktree-1}}
git status  # Check for uncommitted changes
git stash save "rollback-{{run-id}}-stash"  # If needed

cd {{main-project}}
git worktree remove ../{{worktree-1}}
```

#### Step 3: Handle Branches

```bash
# Option A: Delete unmerged branches
git branch -D parallel/{{branch-1}}

# Option B: Keep for investigation
git branch -m parallel/{{branch-1}} investigate/{{branch-1}}-{{date}}
```

#### Step 4: Revert Merged Changes (if applicable)

```bash
# If changes were merged to main
git log --oneline --grep="parallel/" -20  # Find merge commits

# Revert merge commits
git revert -m 1 {{merge-commit-hash}}
```

## Troubleshooting

### "Cannot remove worktree" Error

```bash
# Force remove if worktree is in bad state
rm -rf ../{{worktree}}
git worktree prune
```

### "Branch has uncommitted changes"

```bash
cd ../{{worktree}}
git stash save "emergency-rollback-{{timestamp}}"
# OR
git reset --hard HEAD  # LOSES CHANGES!
```

### "Merge conflicts during rollback"

```bash
# Abort the problematic operation
git merge --abort
# OR
git revert --abort

# Use alternative strategy
git reset --hard {{safe-commit}}
```

## Verification Steps

After rollback, verify system state:

### 1. Check Git State

```bash
# No parallel branches remain
git branch -a | grep parallel/  # Should be empty

# No worktrees remain
git worktree list  # Should show only main

# Clean working tree
git status  # Should be clean
```

### 2. Run Tests

```bash
# Ensure system still works
npm test
npm run lint
npm run build
```

### 3. Verify Functionality

- [ ] Application starts correctly
- [ ] No broken features from partial rollback
- [ ] Database/API connections work
- [ ] No orphaned resources

## Recovery Data

### Commits Created

[[LLM: List all commits created during this run for recovery purposes]]

```
Worktree: {{worktree-1}}
- {{commit-hash}} {{commit-message}}
- {{commit-hash}} {{commit-message}}

Worktree: {{worktree-2}}
- {{commit-hash}} {{commit-message}}
```

### Stashed Changes

If any changes were stashed during execution:

```
{{worktree}}: stash@{0} - {{stash-description}}
```

### File Backups

Critical files backed up before execution:

```
.bmad-workspace/ck-parallel-dev/runs/{{run-id}}/backups/
├── {{file1-backup}}
└── {{file2-backup}}
```

## Post-Rollback Actions

### Report Issues

If rollback was needed due to issues:

1. Document what went wrong
2. Save execution logs: `.bmad-workspace/ck-parallel-dev/runs/{{run-id}}/`
3. Report to team lead
4. Update validation rules if needed

### Clean Up Artifacts

```bash
# Optional: Archive run data before deletion
tar -czf parallel-run-{{run-id}}.tar.gz .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/

# Remove run directory
rm -rf .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/
```

### Update Documentation

- Record lessons learned
- Update rollback procedures if needed
- Note any manual steps that were required

## Emergency Contacts

If automated rollback fails and manual intervention needed:

- **Team Lead**: {{contact info from team config}}
- **DevOps**: {{contact info from team config}}
- **Git Expert**: {{contact info from team config}}

---

**Rollback Guide Generated**: {{timestamp}}  
**Guide Location**: `.bmad-workspace/ck-parallel-dev/runs/{{run-id}}/rollback-guide.md`  
**Keep this guide until**: {{30 days from execution}}

## Appendix: Understanding What Happened

### Execution Timeline

```
{{timestamp}}: Run initiated
{{timestamp}}: Wave 1 started ({{work items}})
{{timestamp}}: Wave 1 completed
{{timestamp}}: Wave 2 started ({{work items}})
{{timestamp}}: {{Failure point if applicable}}
```

### Root Cause (if known)

{{Analysis of why rollback was needed}}

### Prevention Recommendations

{{Suggestions to prevent similar issues}}