Archiving Previous Runs

Learn how Ralph automatically archives completed features when starting new ones

Archiving Previous Runs

Ralph automatically archives completed features when you start a new one. This keeps your workspace clean and preserves history.

How Archiving Works

When you run Ralph with a new prd.json that has a different branchName, Ralph detects the change and archives the previous run.

1. Detect branch change

   Ralph compares the current branchName in prd.json to the previous run’s branch (stored in .last-branch)

   # Previous run
   {"branchName": "ralph/task-status"}
   
   # New run
   {"branchName": "ralph/notifications"}
   
   # Ralph detects: task-status → notifications
   
2. Create archive folder

   Ralph creates a dated folder in archive/:

   archive/
   └── 2026-03-11-task-status/
       ├── prd.json
       └── progress.txt
   

   Format: archive/YYYY-MM-DD-feature-name/

3. Copy files

   Ralph copies the completed run’s files:

   • prd.json (with all stories marked passes: true)
   • progress.txt (all learnings and commit history)
4. Reset progress.txt

   Ralph creates a fresh progress.txt for the new feature:

   # Ralph Progress Log
   Started: 2026-03-11 14:30:00
   ---
   

Archiving happens automatically when you run ./ralph.sh with a new feature. You don’t need to do anything manually.

Archive Structure

After several features, your archive looks like this:

scripts/ralph/
├── ralph.sh
├── prompt.md
├── prd.json              # Current feature
├── progress.txt          # Current progress
├── .last-branch          # Tracks current branch
└── archive/
    ├── 2026-03-08-user-auth/
    │   ├── prd.json
    │   └── progress.txt
    ├── 2026-03-10-task-status/
    │   ├── prd.json
    │   └── progress.txt
    └── 2026-03-11-notifications/
        ├── prd.json
        └── progress.txt

Viewing Archived Runs

See what features Ralph completed:

# List all archived runs
ls -la scripts/ralph/archive/

# View a specific archived PRD
cat scripts/ralph/archive/2026-03-10-task-status/prd.json | jq

# View archived progress log
cat scripts/ralph/archive/2026-03-10-task-status/progress.txt

When Archiving Happens

Scenario 1: Starting a new feature

Setup:

# Current state
cat prd.json | jq '.branchName'
# Output: "ralph/task-status"

Action: You create a new PRD for notifications:

{
  "branchName": "ralph/notifications",
  "userStories": [...]
}

Result: When you run ./ralph.sh, it archives task-status to archive/2026-03-11-task-status/

Scenario 2: Continuing same feature

Setup:

# Current state
cat prd.json | jq '.branchName'
# Output: "ralph/task-status"

Action: You run ./ralph.sh again without changing prd.json

Result: No archiving happens. Ralph continues working on the same feature.

Scenario 3: Manual archiving

Setup: You want to archive manually before Ralph does it automatically

Action:

DATE=$(date +%Y-%m-%d)
FEATURE="task-status"
mkdir -p scripts/ralph/archive/$DATE-$FEATURE
cp scripts/ralph/prd.json scripts/ralph/archive/$DATE-$FEATURE/
cp scripts/ralph/progress.txt scripts/ralph/archive/$DATE-$FEATURE/

Result: Previous run is archived, and you can safely start a new feature.

What Gets Archived

File	Included	Why
prd.json	✅ Yes	Shows completed stories and final state
progress.txt	✅ Yes	Full log of learnings and commits
prompt.md / CLAUDE.md	❌ No	Shared across features
ralph.sh	❌ No	Shared across features
Git commits	❌ No	Already in git history

Git commits are the source of truth. Archives are just for easy reference to Ralph’s learnings and progress logs.

Recovering From Archive

If you need to revisit an old feature:

1. Find the archive

   ls scripts/ralph/archive/ | grep task-status
   # Output: 2026-03-10-task-status
   
2. Restore the files

   cp scripts/ralph/archive/2026-03-10-task-status/prd.json scripts/ralph/
   cp scripts/ralph/archive/2026-03-10-task-status/progress.txt scripts/ralph/
   
3. Check out the git branch

   git checkout ralph/task-status
   
4. Resume Ralph

   ./scripts/ralph/ralph.sh
   

   Ralph will continue from where it left off (first story with passes: false).

Archive Management

How long to keep archives

Archives are small (just JSON and text). Keep them indefinitely or clean up old ones:

# Remove archives older than 90 days
find scripts/ralph/archive -type d -mtime +90 -exec rm -rf {} +

# Or move to long-term storage
mv scripts/ralph/archive ~/ralph-archives-2026/

Searching across archives

Find learnings from previous features:

# Search all progress logs for a pattern
grep -r "revalidatePath" scripts/ralph/archive/*/progress.txt

# Find which features modified a specific file
grep -r "src/app/tasks" scripts/ralph/archive/*/progress.txt

Backing up archives

Archives contain valuable learnings. Back them up:

# Commit to git
git add scripts/ralph/archive/
git commit -m "docs: archive completed Ralph runs"

# Or create a tarball
tar -czf ralph-archives-$(date +%Y-%m).tar.gz scripts/ralph/archive/

Manual Archive Script

If you want to archive manually before Ralph does it automatically:

#!/bin/bash
# scripts/ralph/archive-current.sh

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PRD_FILE="$SCRIPT_DIR/prd.json"
PROGRESS_FILE="$SCRIPT_DIR/progress.txt"
ARCHIVE_DIR="$SCRIPT_DIR/archive"

if [ ! -f "$PRD_FILE" ]; then
  echo "No prd.json to archive"
  exit 1
fi

CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE")
if [ -z "$CURRENT_BRANCH" ]; then
  echo "No branchName in prd.json"
  exit 1
fi

DATE=$(date +%Y-%m-%d)
FOLDER_NAME=$(echo "$CURRENT_BRANCH" | sed 's|^ralph/||')
ARCHIVE_FOLDER="$ARCHIVE_DIR/$DATE-$FOLDER_NAME"

echo "Archiving $CURRENT_BRANCH to $ARCHIVE_FOLDER"
mkdir -p "$ARCHIVE_FOLDER"
cp "$PRD_FILE" "$ARCHIVE_FOLDER/"
cp "$PROGRESS_FILE" "$ARCHIVE_FOLDER/"

echo "Archived successfully"

Usage:

chmod +x scripts/ralph/archive-current.sh
./scripts/ralph/archive-current.sh

Preventing Accidental Overwrites

If you manually edit prd.json to change branchName, Ralph will archive the previous run on next execution.

To prevent accidental archives:

1. Check current branch first

   cat scripts/ralph/prd.json | jq '.branchName'
   cat scripts/ralph/.last-branch
   
2. Use a separate file for new PRDs

   # Don't edit prd.json directly
   # Create a new file first
   nano scripts/ralph/prd-notifications.json
   
   # When ready, replace
   mv scripts/ralph/prd.json scripts/ralph/prd.json.bak
   mv scripts/ralph/prd-notifications.json scripts/ralph/prd.json
   
3. Let Ralph archive automatically

   Just run Ralph with the new prd.json - it will handle archiving:

   ./scripts/ralph/ralph.sh
   # Ralph automatically archives previous run if branch changed
   

Version Control Considerations

Should you commit archives?

Pros of committing archives:

• Full history in git
• Team can see what was completed
• Easy to reference previous learnings

Cons of committing archives:

• Adds noise to git history
• Can grow large over time
• Progress logs might contain sensitive info

Recommendation: Commit archives for significant features, or keep them local and rely on git commits as the source of truth.

Gitignore archives

To exclude archives from git:

# .gitignore
scripts/ralph/archive/
scripts/ralph/.last-branch

You’ll still have git history of commits, which is the real record of what Ralph did.

Debugging Archive Issues

Archive folder not created

Symptom: Branch changed but no archive was created

Debugging:

# Check if .last-branch exists
cat scripts/ralph/.last-branch

# Check permissions
ls -la scripts/ralph/archive/

# Manually create archive dir
mkdir -p scripts/ralph/archive

Wrong files archived

Symptom: Archive contains incomplete or wrong data

Cause: Ralph archives whatever is in prd.json and progress.txt at the time of the branch change.

Solution: Manually copy the correct files:

cp correct-prd.json scripts/ralph/archive/2026-03-11-feature/prd.json

Next Steps

• Debugging - Troubleshoot Ralph issues
• Customizing Prompts - Configure Ralph for your project
• Right-Sizing Stories - Create better PRDs