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 "

# 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: "

# 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

Bad:

[checkpoint] save
[checkpoint] before changes
wip

Rewind Process

When you need to undo:

Step 1: Assess the Damage

# See what changed
git status
git diff --stat

# See recent commits
git log --oneline -5

Step 2: Choose Rewind Method

Scenario A: Just checkpointed, no other commits in between

git reset --hard HEAD~1

Scenario B: Checkpoint was several commits ago

# Find the checkpoint commit
git log --oneline --grep="\[checkpoint\]"

# Revert to it
git reset --hard 

Scenario C: Need to keep some changes, undo others

# Reset specific files
git checkout  -- path/to/file.ts

# Or use interactive reset
git reset -p HEAD~1

Scenario D: Already pushed to remote

# DON'T force push. Instead:
git revert 
# This creates a new commit that undoes the changes (safe for shared repos)

Step 3: Verify the Rewind

# Check the project still works
npm test -- --passWithNoTests 2>&1 | tail -5
# Or
npm run build 2>&1 | tail -5

Integration with Other Skills

• think-tool — Use Think Tool before deciding whether to checkpoint
• subagent-driven-development — Each subagent should checkpoint before starting its task
• requesting-code-review — Auto-fix loop (Step 7) should checkpoint before attempting fixes
• spec-driven-development — Checkpoint before Phase 4 (Implement)

Best Practices

1. Checkpoint early, checkpoint often — Better to have too many than too few
2. Use descriptive messages — "before refactor" not "save"
3. Don't rely on the undo buffer — Editor undo only works within the same session
4. Clean up old checkpoints — After a successful task, squash or drop checkpoint commits
5. Combine with Think Tool — Think first, then checkpoint, then act

Common Mistakes

• Not checkpointing before destructive operations — "I'll just be careful" is not a strategy
• Checkpointing after starting changes — The checkpoint must be BEFORE, not during
• Forgetting to clean up — Old checkpoint files and commits accumulate
• Skipping verification — Always verify after rewind to make sure it worked

Quick Reference

| Action | Command | When | |--------|---------|------| | Git checkpoint | git add -A && git commit -m "[checkpoint] ..." | Before changes | | Stash checkpoint | git stash push -m "checkpoint: ..." | Before experiments | | File backup | cp file file.checkpoint | No git / single file | | Rewind (last commit) | git reset --hard HEAD~1 | Undo all changes | | Rewind (specific) | git reset --hard | Undo to specific point | | Selective undo | git checkout -- | Undo specific file | | Safe undo (pushed) | git revert | Don't force push | | Clean checkpoint commit | git rebase -i HEAD~N | Squash during cleanup |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ChrisLamDev
• Source: ChrisLamDev/hermes-core-skills
• License: MIT
• Homepage: https://chrislamdev.github.io/hermes-core-skills/

Install and usage instructions live in the source repository linked above.