direct-to-ralph

name	direct-to-ralph
description	Use when you have code ready for ralph-o-matic refinement and want to skip brainstorming, planning, and execution phases

Direct to Ralph

You are submitting work directly to ralph-o-matic for iterative refinement. This skill skips brainstorming, planning, and execution — use it when the user already has code or a task they want ralph to refine.

Arguments

Parse the following from the user's command:

• TASK: The task description (required)
• --spec <file>: Path to spec/design doc (enables bounded prompt)
• --max-iterations N: Max ralph loop iterations (default: 50)
• --priority LEVEL: Job priority - high, normal, low (default: normal)
• --open-ended: Use polish prompt without exit criteria
• --branch <name>: Branch to submit (default: current branch)
• --local: Use local repo directory (skip clone). Auto-detected when server is localhost.

Workflow Overview

Step 1: Parse args & validate
         │
Step 2: Check for existing RALPH.md
         │  ├─ Found → Summarize, ask: use existing or create new?
         │  │            ├─ Use existing → Skip to Step 5
         │  │            └─ Create new → Step 3
         │  └─ Not found → Step 3
         │
Step 3: Q&A (fill in gaps from flags)
         │
Step 4: Generate RALPH.md
         │
Step 5: Pre-flight checks (includes local repo detection)
         │
Step 6: Commit, push, submit
         │
Step 7: Report success

---

Step 1: Parse & Validate

Parse the TASK and flags from the user's command. TASK is required — if missing, ask:

What should ralph work on?

---

Step 2: Check for Existing RALPH.md

Look for a RALPH.md file in the repository root.

If found:

• Read the file
• Summarize its contents in 2 sentences
• Ask the user using AskUserQuestion:
  • "Use this existing RALPH.md" → Skip to Step 5 (pre-flight checks)
  • "Create a new one" → Continue to Step 3

If not found: Continue to Step 3.

---

Step 3: Q&A

Ask only what isn't already provided via flags. Use AskUserQuestion for each.

Prompt type (ask if neither --spec nor --open-ended was provided):

Option	Description
Bounded with spec	Ralph stops when spec requirements are satisfied. Ask for the spec file path.
Open-ended polish	Ralph keeps improving until max iterations reached or manually stopped.
Custom	User will write or edit RALPH.md themselves. Open the file for them and skip to Step 5 after they confirm.

Priority (ask if --priority not provided): Offer high / normal (default) / low.

Max iterations (ask if --max-iterations not provided): Ask conversationally (do NOT use AskUserQuestion — numeric input conflicts with option selection). Suggest common values: 25, 50, 100, 200, 500, 1000. Default 50. Accept any number the user provides.

---

Step 4: Generate RALPH.md

Based on the prompt type selected, generate the prompt file.

Bounded prompt (with spec):

You are refining code to meet a specification. The user is unavailable — do the work without asking for input.

Spec: {SPEC_FILE}
Progress: docs/plans/{BRANCH}-ralph-status.md
Test baseline: docs/plans/{BRANCH}-test-baseline.md (tests that already failed before this work — these do NOT block)

Steps:
1. Read the spec, progress file, and test baseline to understand current state
2. Search the codebase before assuming anything is missing — do not reimplement existing code
3. Pick the single highest-impact remaining task
4. Implement it, keeping the change focused and testable
5. Run tests — compare against the baseline. Fix any NEW failure (not in the baseline) and any new build break before moving on. Pre-existing baseline failures are NOT your job; do not chase a fully green suite.
6. Update the progress file: mark completed items, add discovered work, note what's next
7. Commit and push

The code may have been drafted by another agent. Do not trust it. Verify against the spec.

Wired-and-fed: a task is done only when its component is constructed at the REAL composition root (not just in a test) AND fed real data from a producer that exists — not nil/empty/hardcoded. For every new exported field/collaborator/config, `grep -rn <Symbol>` and confirm it is populated outside `*_test.go`. A fully green suite does NOT by itself mean done: green over-mocked tests can hide an unwired feature — probe "would this test still pass if the prod input were nil?"

When all spec requirements are satisfied AND wired-and-fed AND there are no NEW test failures vs the baseline (and nothing that built at baseline is now broken), output:
<promise>FINIT</promise>

Otherwise, output:
<promise>CLOSER</promise>

Output exactly one tag, then stop.

Open-ended prompt:

You are improving this codebase toward production quality. The user is unavailable — do the work without asking for input.

Progress: docs/plans/{BRANCH}-ralph-status.md
Test baseline: docs/plans/{BRANCH}-test-baseline.md (tests that already failed before this work — these do NOT block)

Steps:
1. Read the progress file and test baseline to understand what's been done and what remains
2. Search the codebase before assuming anything is missing
3. Pick the single highest-impact improvement
4. Implement it, keeping the change focused and testable
5. Run tests — compare against the baseline. Fix any NEW failure (not in the baseline) and any new build break before moving on. Pre-existing baseline failures are NOT your job; do not chase a fully green suite.
6. Update the progress file: mark completed items, add discovered work, note what's next
7. Commit and push

Keep every improvement wired-and-fed: constructed at the real composition root and fed a real producer (not nil/empty/hardcoded, not only set in tests) — a green over-mocked test can hide an unwired change. Do not output a <promise> tag. Continue improving until stopped.

Write the generated prompt to RALPH.md in the repository root.

---

Step 5: Pre-flight Checks

Run these checks before submission:

# 1. Working tree clean
if [ -n "$(git status --porcelain)" ]; then
    echo "✗ Uncommitted changes detected"
    git status --short
    # Stage and commit remaining changes
    git add -A
    git commit -m "chore: pre-ralph cleanup"
fi
echo "✓ Working tree clean"

# 2. Branch pushed to origin
BRANCH=$(git branch --show-current)
if ! git ls-remote --exit-code origin "$BRANCH" &>/dev/null; then
    echo "Pushing branch to origin..."
    git push -u origin "$BRANCH"
fi
echo "✓ Branch '$BRANCH' pushed to origin"

# 3. Server reachable
if ! ralph-o-matic status &>/dev/null; then
    echo "✗ Cannot reach ralph-o-matic server"
    exit 1
fi
echo "✓ Server reachable"

# 4. Branch not already in queue
SERVER=$(ralph-o-matic config | grep '^server:' | awk '{print $2}')
EXISTING=$(curl -sf "$SERVER/api/jobs?status=queued,running,paused" | jq -r ".jobs[] | select(.branch == \"$BRANCH\") | .id" 2>/dev/null | head -1)
if [ -n "$EXISTING" ]; then
    echo "✗ Branch already in queue as job #$EXISTING"
    exit 1
fi
echo "✓ Branch not in queue"

Record the branch-point test baseline

Before submitting, capture which tests already fail right now so the loop gates on NEW-vs-baseline rather than demanding a fully green suite. The repo MAY be red on arrival — that is fine; pre-existing failures are not this work's job.

1. Run the project's test command (auto-detect it: make test, npm test, go test ./..., pytest, cargo test, dotnet test, etc.). For a mixed-language repo, run each suite.
2. For each suite, capture whether it built/compiled, the pass/fail counts, and the stable identifier of each failing test (no timestamps/durations).
3. Write the result to docs/plans/{BRANCH}-test-baseline.md — per suite: the exact command, build-ok status, pass/fail counts, and the list of pre-existing failing test ids. If a suite fails to build, note BUILD FAILED with a one-line summary. If no test suite exists, note that and continue.

This is the file the generated RALPH.md prompt references. Pre-existing failures here are logged, not fixed, and must not block the loop. Commit this file alongside RALPH.md in Step 6.

Local Server Detection

After pre-flight checks pass, determine whether the ralph server is local.

How to detect: Read the configured server URL from ralph-o-matic config. If it contains localhost or 127.0.0.1, the server is local.

If --local was passed: Use local mode without asking.

If server is local and --local was NOT passed: Ask the user with AskUserQuestion:

Option	Description
Use local repo (Recommended)	Ralph works directly in your checkout — no clone, faster startup, changes pushed after each pass. Don't edit these files while ralph is running.
Clone as usual	Ralph clones into its own workspace. Slower but your working tree stays untouched.

If the user chooses local repo: Get the repo root with git rev-parse --show-toplevel. Store this as LOCAL_DIR for use in Step 6.

If server is NOT local: Skip this — remote servers can't access local paths.

---

Step 6: Commit, Push, Submit

# Commit RALPH.md (and the recorded test baseline) if generated or modified
if [ -n "$(git status --porcelain RALPH.md "docs/plans/${BRANCH}-test-baseline.md")" ]; then
    git add RALPH.md "docs/plans/${BRANCH}-test-baseline.md"
    git commit -m "chore: add ralph review prompt and test baseline"
    git push
fi

# Submit job
# If LOCAL_DIR is set, pass --working-dir to use the local repo directly
ralph-o-matic submit \
    --priority {PRIORITY} \
    --max-iterations {MAX_ITERATIONS} \
    ${LOCAL_DIR:+--working-dir "$LOCAL_DIR"}

---

Step 7: Report Success

Shipped to Ralph-o-matic!

  Job ID:         #{JOB_ID}
  Branch:         {BRANCH}
  Priority:       {PRIORITY}
  Max Iterations: {MAX_ITERATIONS}
  Prompt:         {PROMPT_TYPE}
  Mode:           {LOCAL_DIR ? "local repo (direct)" : "cloned workspace"}

  Dashboard:      {SERVER_URL}/jobs/{JOB_ID}

  Monitor: ralph-o-matic logs {JOB_ID} --follow

If local mode was used, add:

  Note: Ralph is working directly in {LOCAL_DIR}.
        Changes are pushed to the remote after each pass.
        Avoid editing files in this repo until the job completes.

---

Error Handling

Server Unreachable

Cannot reach ralph-o-matic server.

Options:
1. Start the server: ralph-o-matic-server
2. Change server:    ralph-o-matic config set server http://host:9090
3. Skip submission:  push the branch and submit later manually

Branch Already Queued

Branch '{BRANCH}' is already queued as job #{ID}.

Options:
1. Cancel existing job:  ralph-o-matic cancel {ID}
2. Use a different branch
3. Wait for the current job to finish