Skip to content

Ralph Wiggum Launch Checklist (Pre-Flight)

Use this checklist before starting an overnight autonomous run.

0) One-Time Machine Setup

  • git installed and configured
  • gh installed and authenticated (gh auth status)
  • uv installed (uv --version)
  • Claude Code CLI installed (claude --version)
  • tmux installed (recommended for overnight runs)
  • Timeout command available (Linux: timeout; macOS: brew install coreutils for gtimeout)

1) Repo Pre-Flight (Required Every Run)

From repo root:

pwd
git status
git branch --show-current
  • Working tree is clean (no uncommitted changes)
  • You will run the loop on a ralph-wiggum-* branch (not on main/dev)
  • PROMPT.md and PROGRESS.md exist
  • SSOT docs exist for the run:
  • Debt sprint: docs/_debt/README.md and the referenced docs/_debt/debt-*.md decks
  • Spec work (when approved): docs/_specs/ (active) and/or docs/_archive/specs/ (implemented SSOT)

Sync and sanity:

git fetch origin
# Recommended: start a fresh Ralph branch from latest dev (avoid rebasing)
git checkout dev
git pull --ff-only origin dev
git checkout -b ralph-wiggum-<sprint>
git push -u origin ralph-wiggum-<sprint>
make sync-frozen
make lock-check
make ci
make smoke
make test-all  # Full suite (includes requires_network; may hit real APIs)
  • make ci passes
  • make smoke passes
  • make test-all passes (recommended before/after a long sprint; may require network)

2) Safety Checks

  • You understand the file boundaries in docs/_ralphwiggum/protocol.md (“Forbidden to change”)
  • You are comfortable with the iteration cap (MAX=50)
  • You have disk space (Lean + caches can grow)

Start a tmux session:

MAX=50 ITER_TIMEOUT=1200 tmux new-session -s erdos-ralph './scripts/ralph-loop.sh'

This uses the repo’s loop runner (scripts/ralph-loop.sh), which: - writes per-iteration logs to logs/ralph/iteration_*.log - enforces per-iteration timeouts (avoids hangs) - avoids piping Claude output through tee (but timeouts can still trigger EPIPE in the CLI)

./scripts/ralph-loop.sh

4) Monitoring Instructions

In another pane:

watch -n 10 'git log --oneline -10'
watch -n 10 'head -80 PROGRESS.md'

Recommended: run the watchdog in a separate pane (fails fast on hangs / guardrail errors):

MAX_AGE=1500 ./scripts/ralph-watchdog.sh  # keep MAX_AGE >= ITER_TIMEOUT + buffer

If the watchdog exits non-zero, inspect: - logs/ralph/watchdog.log - the most recent logs/ralph/iteration_*.log

If the loop appears stuck:

make ci
git status

5) Abort Instructions

  • Stop the loop: Ctrl+C (inside the tmux pane running it)
  • If needed, kill tmux session: tmux kill-session -t erdos-ralph

Rollback options:

git status
git log --oneline -10

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Revert a specific commit (safe on shared branches)
git revert <sha>