Rollback Changes

Automatically rollback changes from failed workflow phases by reading changes log files and reversing all tracked modifications.

When to Use

• Workflow phase fails and needs state restoration
• Automated rollback after failed bug fixes
• Restore previous state after failed security patches
• Cleanup after failed refactoring operations
• Error recovery in worker agents
• Quality gate failures requiring revert

Instructions

Step 1: Read Changes Log File

Use Read tool to load the changes log file.

Expected Input:

• changes_log_path: String (path to changes log JSON, e.g., .bug-changes.json)
• phase: String (workflow phase name, e.g., "bug-fixing")
• confirmation_required: Boolean (default: true, ask user before rollback)

Tools Used: Read

Step 2: Parse Changes Log

Parse the JSON content and validate structure.

Required Fields:

• phase: String (workflow phase that made changes)
• timestamp: String (ISO-8601 timestamp)
• files_modified: Array of objects with {path, backup} (files with backups)
• files_created: Array of strings (new files created)
• commands_executed: Array of strings (commands that were run)
• git_commits: Array of strings (commit SHAs if any)

Optional Fields:

• artifacts: Array of strings (temporary files to remove)
• plan_files: Array of strings (plan files to remove)
• metadata: Object (additional context)

Step 3: Request Confirmation (if required)

If confirmation_required is true, ask user for confirmation.

Confirmation Prompt:

Rollback changes from phase "{phase}"?

Changes to revert:
- Files modified: {count}
- Files created: {count}
- Commands executed: {count}
- Git commits: {count}

This action will:
1. Restore {count} files from backups
2. Delete {count} created files
3. Revert {count} commands
4. Revert {count} git commits

Proceed with rollback? (yes/no)

If user says "no": Return without taking action (dry run result)

If confirmation_required is false: Skip confirmation and proceed

Step 4: Restore Modified Files

For each file in files_modified, restore from backup.

Restoration Process:

# For each {path, backup} in files_modified:
if [ -f "{backup}" ]; then
  cp "{backup}" "{path}"
  echo "✓ Restored {path} from {backup}"
else
  echo "⚠ Backup not found: {backup} (skipping)"
fi

Error Handling:

• Missing backup file: Log warning, continue with other files
• Copy failure: Log error, continue with other files
• Permission issues: Log error, continue with other files

Tools Used: Bash

Step 5: Delete Created Files

For each file in files_created, delete if it exists.

Deletion Process:

# For each file in files_created:
if [ -f "{file}" ]; then
  rm "{file}"
  echo "✓ Deleted created file: {file}"
elif [ -d "{file}" ]; then
  rm -rf "{file}"
  echo "✓ Deleted created directory: {file}"
else
  echo "⚠ File not found (already deleted?): {file}"
fi

Error Handling:

• File not found: Log warning (may already be deleted)
• Permission issues: Log error, continue with other files
• Directory not empty: Use rm -rf with caution

Tools Used: Bash

Step 6: Revert Commands

For each command in commands_executed, attempt to revert.

Revert Mapping:

• pnpm install → pnpm install (re-run to restore lockfile)
• git add {files} → git restore --staged {files}
• git commit → Handled in Step 7
• pnpm build → rm -rf dist/ (remove build artifacts)
• Custom commands → Log only (cannot automatically revert)

Revert Process:

# For each command:
case "{command}" in
  "pnpm install")
    pnpm install
    echo "✓ Re-ran pnpm install to restore dependencies"
    ;;
  "git add "*)
    git restore --staged .
    echo "✓ Unstaged all files"
    ;;
  "pnpm build")
    rm -rf dist/
    echo "✓ Removed build artifacts"
    ;;
  *)
    echo "⚠ Cannot auto-revert: {command} (manual intervention required)"
    ;;
esac

Error Handling:

• Command fails: Log error, continue with other commands
• Unknown command: Log warning, cannot revert
• Already reverted: Log info, continue

Tools Used: Bash

Step 7: Revert Git Commits

For each commit SHA in git_commits, revert the commit.

Revert Process:

# For each SHA in git_commits (in reverse order):
git revert --no-edit {sha}
if [ $? -eq 0 ]; then
  echo "✓ Reverted commit {sha}"
else
  echo "❌ Failed to revert commit {sha} (may have conflicts)"
fi

Error Handling:

• Revert conflicts: Log error, provide manual instructions
• Commit not found: Log error, skip commit
• Detached HEAD: Log error, skip git operations

Tools Used: Bash

Step 8: Cleanup Artifacts

Remove temporary files and plan files.

Cleanup Process:

# Remove plan files
rm -f .{workflow}-plan.json

# Remove other artifacts if specified
for artifact in {artifacts}; do
  rm -f "{artifact}"
  echo "✓ Removed artifact: {artifact}"
done

# Remove rollback backups (optional, only if all succeeded)
if [ {all_succeeded} == true ]; then
  rm -rf .rollback/
  echo "✓ Removed rollback backups"
fi

Tools Used: Bash

Step 9: Generate Rollback Report

Create a structured report of all actions taken.

Report Structure:

{
  "success": true|false,
  "phase": "bug-fixing",
  "actions_taken": [
    "Restored 3 files from backups",
    "Deleted 2 created files",
    "Reverted 1 git commit",
    "Cleaned up 2 artifacts"
  ],
  "files_restored": 3,
  "files_deleted": 2,
  "commands_reverted": 1,
  "git_commits_reverted": 1,
  "artifacts_cleaned": 2,
  "errors": [],
  "warnings": [
    "Backup not found: .rollback/file.backup (skipped)"
  ],
  "timestamp": "2025-10-18T14:45:00Z",
  "duration_ms": 1234
}

Tools Used: Write

Step 10: Return Structured Output

Return complete rollback result.

Expected Output:

{
  "success": true,
  "phase": "bug-fixing",
  "actions_taken": [
    "Restored src/app.ts from .rollback/src-app.ts.backup",
    "Deleted src/new-file.ts",
    "Reverted git commit abc123",
    "Removed artifact .bug-fixing-plan.json"
  ],
  "files_restored": 1,
  "files_deleted": 1,
  "commands_reverted": 0,
  "git_commits_reverted": 1,
  "artifacts_cleaned": 1,
  "errors": [],
  "warnings": [],
  "timestamp": "2025-10-18T14:45:00Z",
  "duration_ms": 1234
}

Error Handling

• Missing Changes Log: Return error "Changes log not found at {path}"
• Invalid JSON: Return error "Invalid JSON in changes log: {details}"
• Missing Required Fields: Return error "Changes log missing required field: {field}"
• Backup Not Found: Log warning, continue with other files (partial rollback)
• File Deletion Failed: Log error, continue with other files
• Git Revert Failed: Log error with conflict details, continue with other operations
• User Declined: Return dry run result with success: false, user_declined: true
• Partial Rollback: Return success: true with warnings array documenting issues

Examples

Example 1: Full Rollback (All Operations Succeed)

Input:

{
  "changes_log_path": ".bug-changes.json",
  "phase": "bug-fixing",
  "confirmation_required": false
}

Changes Log Content:

{
  "phase": "bug-fixing",
  "timestamp": "2025-10-18T14:30:00Z",
  "files_modified": [
    { "path": "src/app.ts", "backup": ".rollback/src-app.ts.backup" },
    { "path": "src/utils.ts", "backup": ".rollback/src-utils.ts.backup" }
  ],
  "files_created": ["src/new-helper.ts"],
  "commands_executed": ["pnpm install", "pnpm build"],
  "git_commits": ["abc123def456"],
  "artifacts": [".bug-fixing-plan.json"]
}

Output:

{
  "success": true,
  "phase": "bug-fixing",
  "actions_taken": [
    "Restored src/app.ts from .rollback/src-app.ts.backup",
    "Restored src/utils.ts from .rollback/src-utils.ts.backup",
    "Deleted src/new-helper.ts",
    "Re-ran pnpm install to restore dependencies",
    "Removed build artifacts (dist/)",
    "Reverted git commit abc123def456",
    "Removed artifact .bug-fixing-plan.json"
  ],
  "files_restored": 2,
  "files_deleted": 1,
  "commands_reverted": 2,
  "git_commits_reverted": 1,
  "artifacts_cleaned": 1,
  "errors": [],
  "warnings": [],
  "timestamp": "2025-10-18T14:45:00Z",
  "duration_ms": 2345
}

Example 2: Partial Rollback (Some Backups Missing)

Input:

{
  "changes_log_path": ".security-changes.json",
  "phase": "security-remediation",
  "confirmation_required": false
}

Changes Log Content:

{
  "phase": "security-remediation",
  "timestamp": "2025-10-18T14:30:00Z",
  "files_modified": [
    { "path": "src/auth.ts", "backup": ".rollback/src-auth.ts.backup" },
    { "path": "src/db.ts", "backup": ".rollback/src-db.ts.backup" }
  ],
  "files_created": ["src/new-auth.ts"],
  "commands_executed": [],
  "git_commits": []
}

Scenario: Backup for src/db.ts is missing

Output:

{
  "success": true,
  "phase": "security-remediation",
  "actions_taken": [
    "Restored src/auth.ts from .rollback/src-auth.ts.backup",
    "Deleted src/new-auth.ts"
  ],
  "files_restored": 1,
  "files_deleted": 1,
  "commands_reverted": 0,
  "git_commits_reverted": 0,
  "artifacts_cleaned": 0,
  "errors": [],
  "warnings": ["Backup not found: .rollback/src-db.ts.backup (file not restored)"],
  "timestamp": "2025-10-18T14:45:00Z",
  "duration_ms": 456
}

Example 3: Dry Run (User Declines)

Input:

{
  "changes_log_path": ".refactor-changes.json",
  "phase": "refactoring",
  "confirmation_required": true
}

User Response: "no"

Output:

{
  "success": false,
  "phase": "refactoring",
  "user_declined": true,
  "actions_taken": [],
  "files_restored": 0,
  "files_deleted": 0,
  "commands_reverted": 0,
  "git_commits_reverted": 0,
  "artifacts_cleaned": 0,
  "errors": [],
  "warnings": [],
  "timestamp": "2025-10-18T14:45:00Z",
  "duration_ms": 0
}

Example 4: No Changes Log (File Missing)

Input:

{
  "changes_log_path": ".nonexistent-changes.json",
  "phase": "unknown",
  "confirmation_required": false
}

Output:

{
  "success": false,
  "phase": "unknown",
  "actions_taken": [],
  "files_restored": 0,
  "files_deleted": 0,
  "commands_reverted": 0,
  "git_commits_reverted": 0,
  "artifacts_cleaned": 0,
  "errors": ["Changes log not found at .nonexistent-changes.json"],
  "warnings": [],
  "timestamp": "2025-10-18T14:45:00Z",
  "duration_ms": 10
}

Example 5: Git Revert with Conflicts

Input:

{
  "changes_log_path": ".bug-changes.json",
  "phase": "bug-fixing",
  "confirmation_required": false
}

Changes Log Content:

{
  "phase": "bug-fixing",
  "timestamp": "2025-10-18T14:30:00Z",
  "files_modified": [],
  "files_created": [],
  "commands_executed": [],
  "git_commits": ["abc123", "def456"]
}

Scenario: Reverting abc123 causes conflicts

Output:

{
  "success": true,
  "phase": "bug-fixing",
  "actions_taken": ["Reverted git commit def456"],
  "files_restored": 0,
  "files_deleted": 0,
  "commands_reverted": 0,
  "git_commits_reverted": 1,
  "artifacts_cleaned": 0,
  "errors": ["Failed to revert commit abc123: Merge conflict in src/app.ts"],
  "warnings": ["Manual resolution required for commit abc123"],
  "timestamp": "2025-10-18T14:45:00Z",
  "duration_ms": 876
}

Validation

• [ ] Reads and parses changes log correctly
• [ ] Requests user confirmation when required
• [ ] Restores files from backups successfully
• [ ] Deletes created files correctly
• [ ] Reverts commands appropriately
• [ ] Handles git revert operations
• [ ] Cleans up artifacts
• [ ] Generates structured report
• [ ] Handles partial rollback gracefully
• [ ] Returns clear error messages for failures
• [ ] Logs warnings for non-critical issues
• [ ] Completes within reasonable time (< 30 seconds typical)

Safety Features

Confirmation by Default

• Always ask for confirmation unless explicitly disabled
• Show clear summary of what will be reverted
• Allow user to cancel before any changes

Partial Rollback Acceptable

• Don't fail entirely if some backups are missing
• Continue with other operations when one fails
• Document all issues in warnings array

No Silent Failures

• Log all errors and warnings explicitly
• Return detailed actions_taken array
• Provide troubleshooting context in errors

Backup Verification

• Never delete original files without verifying backup exists
• Check backup file exists before restoration
• Preserve backups until full rollback succeeds

Audit Trail

• Log all rollback actions for debugging
• Include timestamps and durations
• Return complete report for documentation

Integration with Workers

Workers should create changes log files during operations:

## Step 2: Track Changes

Before making any modifications:

1. Create changes log: `.{domain}-changes.json`
2. For each file modified:
   - Create backup in `.rollback/{path}.backup`
   - Add to `files_modified` array
3. For each file created:
   - Add to `files_created` array
4. For each command executed:
   - Add to `commands_executed` array
5. For each git commit:
   - Add SHA to `git_commits` array
6. Write changes log after each modification

## Step 5: Rollback on Failure

If quality gate fails or error occurs:

1. Use rollback-changes Skill with:
   - changes_log_path: ".{domain}-changes.json"
   - phase: "{current-phase}"
   - confirmation_required: false (automated rollback)
2. If rollback succeeds, report clean state
3. If rollback fails, report partial state with warnings

Supporting Files

• changes-log-schema.json: JSON schema for changes log format (see below)

Notes

• Rollback operations are best-effort (may not be 100% reversible)
• Git revert operations may require manual conflict resolution
• Some commands (custom scripts) cannot be automatically reverted
• Backups should be stored in .rollback/ directory (gitignored)
• Changes log files should be temporary (removed after successful completion)
• Partial rollback is acceptable and documented in warnings
• Always verify backup exists before deletion operations