ralph-plan

Ralph Plan

Prepare a project for a ralph refinement run by setting up tracking documents and populating them based on the work scope.

Usage

/ralph-plan                           # Scope = changes in current branch vs main
/ralph-plan PR #123                   # Scope = changes in a specific PR
/ralph-plan "the new auth system"     # Scope = user-described body of work

Process

Follow each phase in order. Do not skip phases.

---

Phase 1: Define Scope

Parse the user's arguments:

• No arguments: Scope is changes in the current branch compared to the default branch. Run:

  git log --oneline $(git merge-base HEAD main)..HEAD
  git diff --name-only $(git merge-base HEAD main)..HEAD
  

  If no divergence from main (i.e., we ARE on main or no commits ahead), ask: "You're on the default branch with no divergent commits. What should the scope be?"

• PR number (e.g., #123 or 123): Fetch the PR diff:

  gh pr diff 123
  gh pr view 123 --json title,body
  

• Free text description: Use the description as scope context. Still run git diff --name-only against main to find changed files if any exist.

Store the result as SCOPE — a description of what's being reviewed plus the list of changed files.

---

Phase 2: Archive Previous Documents

Check for existing files:

• RALPH.md
• docs/reference/gaps-identified.md
• docs/reference/focus-areas.md

If none exist: Skip to Phase 3.

If any exist:

1. Determine today's date as YYYY-MM-DD.
2. Determine the intra-day plan number — count today's existing backups (using one representative file type so the count is robust regardless of how many files each backup contains) and add 1:

   echo $(( $(ls docs/reference/YYYY-MM-DD-historical-focus-areas-*.md 2>/dev/null | wc -l) + 1 ))
   

   If zero exist, the plan number is 1.
3. For each existing file, move (rename) it — do NOT copy it. The original must no longer exist at its working-tree location afterward:
   • RALPH.md → docs/reference/YYYY-MM-DD-historical-RALPH-{plan#}.md
   • gaps-identified.md → docs/reference/YYYY-MM-DD-historical-gaps-identified-{plan#}.md
   • focus-areas.md → docs/reference/YYYY-MM-DD-historical-focus-areas-{plan#}.md
4. Report: "Archived existing tracking docs as plan #{plan#} for {date}."