checkpoints-and-rewind

Checkpoints & Rewind

Overview

Before making risky or irreversible changes, create a checkpoint. If things go wrong, rewind to the checkpoint. This gives you the confidence to experiment without fear of breaking things.

Core principle: Every multi-file change starts with a safety net.

When to Use

• Before large refactors — Moving code, renaming files, changing architecture
• Before deleting anything — Files, directories, database data
• Before destructive git operations — git reset, git rebase, git clean
• Before trying experimental approaches — "Let's see if this works"
• At the start of any task that modifies 3+ files
• Before running auto-fix in code review (Step 7 of requesting-code-review)

Do NOT use for: Single-file edits, reading files, running tests, or any operation that's trivially undoable.

How to Create a Checkpoint

Method 1: Git Commit (Recommended)

# Before making changes
git add -A && git commit -m "[checkpoint] before <description>"

# Make your changes...

# If things go wrong:
git reset --hard HEAD~1

# If things go right:
# Keep the checkpoint commit, or squash it later

Method 2: Git Stash (For Experiments)

# Before making changes
git stash push -m "checkpoint: <description>"

# Make your changes... (starting from clean state)

# If things go wrong:
git stash pop  # restore the checkpoint (undoes your changes)

# If things go right:
git stash drop  # discard the checkpoint

Method 3: Manual Backup (No Git)

# Before making changes
cp -r important_file.ts important_file.ts.checkpoint

# Make your changes...

# If things go wrong:
cp important_file.ts.checkpoint important_file.ts

# Clean up after success:
rm important_file.ts.checkpoint

Naming Convention

Always include:

• [checkpoint] prefix (easy to search in git log)
• What you're about to do
• Date/time if helpful

Good:

[checkpoint] before refactoring ChantingHall to adapter pattern
[checkpoint] before trying experimental rendering approach
[checkpoint] before deleting old story-data.js