---
name: ralph-prep
description: Prepare a new Ralph Loop run — create the run directory under .ralph/ and interactively generate instructions.md. Use this whenever the user wants to set up a Ralph loop, prepare a new autonomous task, or says "/ralph-prep". Also trigger when the user mentions creating Ralph instructions or setting up an agent loop.
---

# Ralph Loop Preparation

You are helping the user set up a new Ralph Loop run. A Ralph Loop is an autonomous agent pattern where Claude is invoked repeatedly, performing one task per iteration with no memory between iterations. Persistence happens through files.

Read `.claude/rules/ralph-loops.md` for the full guide if you need context on how Ralph works.

## Your Job

1. Interview the user to understand the task
2. Create the run directory under `.ralph/`
3. Generate a complete `instructions.md`

The conversation language is German (per project statutes). The generated files are in English.

## Interview

Ask these questions to understand the task. You don't need to ask them one-by-one in a rigid sequence — have a natural conversation in German. But make sure you cover all of them before generating the file.

### Required

1. **Run name** — short, kebab-case identifier (e.g. `implement-auth`, `refine-api-spec`). This becomes the directory name under `.ralph/`.
2. **Role** — What is Ralph doing? One sentence. (e.g. "Refine user stories until implementation-ready", "Implement the event creation API endpoint with TDD", "Review all components for accessibility issues")
3. **Startup files** — Which files should Ralph read at the start of each iteration to understand the project state? The following are always included automatically — don't ask the user about these:
   - `{{RUN_DIR}}/progress.txt`
   - `{{RUN_DIR}}/chief-wiggum.md`
   - `{{RUN_DIR}}/answers.md`
   - `{{RUN_DIR}}/questions.md`
   - `CLAUDE.md`

   Ask the user what else Ralph needs — spec files, source code, config files, etc.
4. **Writable files** — Which files may Ralph modify? Be specific. Ralph should never modify files it only needs for context.
5. **Task priorities** — What should Ralph do in each iteration? Help the user define a priority list. The first two priorities (Chief Wiggum action items, process answers) and the last one (completion signal) are always the same. Help the user define the middle priorities that are specific to their task.

### Optional (suggest if relevant)

6. **Guardrails** — Any decisions Ralph must NOT make on its own? (e.g. "do not choose dependencies", "do not modify the database schema without asking")

## Generating instructions.md

Use the following structure. Adapt the content based on the interview answers — don't include sections that aren't relevant to the task.

```markdown
# Ralph Loop — {role title}

{One paragraph describing what Ralph does in this run.}

## CRITICAL RULE: One Task Per Iteration

You MUST perform exactly ONE task per iteration. Not two, not "a few small ones", not "all remaining items". ONE.

After completing your single task:
1. Append a short summary of what you did to `{{RUN_DIR}}/progress.txt`.
2. Stop. Do not look for more work. Do not "while I'm at it" anything.

The only exception: if the single task you perform reveals that the work is complete, you may additionally output `<promise>COMPLETE</promise>`.

## Startup: Read Project State

At the start of every iteration, read these files in order:

1. `{{RUN_DIR}}/progress.txt` — what previous iterations did (your memory across iterations).
2. `{{RUN_DIR}}/chief-wiggum.md` — notes from Chief Wiggum. Items under `## Action Required` have highest priority.
3. `{{RUN_DIR}}/answers.md` — check if the human answered any open questions.
4. `{{RUN_DIR}}/questions.md` — open and resolved questions.
5. `CLAUDE.md` — project statutes and principles.
{additional startup files, numbered starting at 6}

## Task Selection (Priority Order)

Pick the FIRST applicable task from this list. Do that ONE task, then stop.

### Priority 1: Chief Wiggum action items
If `{{RUN_DIR}}/chief-wiggum.md` has items under `## Action Required`, address the FIRST one that hasn't been addressed yet (check `{{RUN_DIR}}/progress.txt`). Do NOT modify `{{RUN_DIR}}/chief-wiggum.md`.

### Priority 2: Process answers
If `{{RUN_DIR}}/answers.md` contains an answer, process it. Remove the processed entry from `{{RUN_DIR}}/answers.md`.

{task-specific priorities — numbered starting at 3}

### Priority N: Complete
If all work is done, all answers processed, and all Chief Wiggum action items addressed:
Output `<promise>COMPLETE</promise>` and stop.

## File Ownership

Respect these boundaries strictly:

| File | Owner | You may... |
|------|-------|------------|
| `{{RUN_DIR}}/progress.txt` | Ralph | Read and append |
| `{{RUN_DIR}}/questions.md` | Ralph | Read and write |
| `{{RUN_DIR}}/answers.md` | Human | **Read only.** Only remove entries you have already processed. |
| `{{RUN_DIR}}/chief-wiggum.md` | Chief Wiggum | **Read only.** Never modify. |
| `CLAUDE.md` | Human | **Read only.** Never modify. |
{additional file ownership rows from interview}

{optional: ## Handling Uncertainty section with question format}

{optional: ## Rules section with task-specific constraints}
```

### Key conventions

- Always use `{{RUN_DIR}}` for paths to files inside the run directory. The script substitutes this at runtime.
- All other paths are relative to the project root.
- The one-task-per-iteration rule and the `<promise>COMPLETE</promise>` signal are non-negotiable — always include them.
- The first two priorities (Chief Wiggum items, process answers) and the last (complete) are always present. Task-specific priorities go in between.

## After Generating

1. Create the directory: `mkdir -p .ralph/{run-name}`
2. Write `instructions.md` into it
3. Give the user a complete, copy-ready command to start the loop. Pick sensible defaults for `-n` and `-m` based on the task complexity (e.g. simple verification tasks: `-n 10 -m sonnet`, complex coding tasks: `-n 30 -m opus`). Example:

```
./ralph.sh .ralph/verify-impl-order -n 10 -m sonnet
```

4. Briefly mention the other options (`-n`, `-m`, `-t`) in case they want to adjust