ralph

mgreenly 的头像作者 mgreenly

Ralph loop - iterative requirement completion harness

📖 中文导读:Ralph loop - iterative requirement completion harness 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: ralph description: Ralph loop - iterative goal completion harness

Ralph

Braindead agentic loop that iteratively works toward a goal until done or time expires. Named after Ralph Wiggum - just keep trying until it works.

Philosophy

No sophisticated planning. No complex orchestration. Just:

  1. Read the goal
  2. Try to make progress
  3. Commit progress
  4. Repeat until DONE

History provides learning without complex state management. Time budget prevents runaway costs.

Usage

.claude/harness/ralph/run \
  --goal=path/to/goal.md \
  [--duration=4h] \
  [--model=sonnet] \
  [--reasoning=low] \
  [--spinner] \
  [--continue] \
  [--no-art]

Flags:

  • --goal - Path to goal markdown file (required)
  • --duration - Time budget (e.g., 4h, 200m); unlimited if omitted
  • --model - haiku, sonnet, opus (default: sonnet)
  • --reasoning - none, low, med, high (default: low)
  • --spinner - Enable progress spinner (off by default)
  • --continue - Continue from existing progress
  • --no-art - Suppress ASCII art in header

Reasoning levels (fraction of model's max thinking budget):

  • none = 0 (no thinking)
  • low = 25% of max
  • med = 50% of max
  • high = 100% of max

Goal File Format

Markdown file with required ## Objective section:

## Objective

Brief description of what needs to be accomplished.

## Reference

Optional pointers to specs, plans, or other context.

## Outcomes

Optional list of specific outcomes that indicate completion.

## Acceptance

Optional acceptance criteria (e.g., `check-build` passes).

Required: ## Objective section must exist.

State files are derived from the goal file name:

  • <base>-goal.md → <base>-progress.jsonl, <base>-summary.md
  • Example: rel-08/ralph-code-removal-goal.md produces:
    • rel-08/ralph-code-removal-progress.jsonl
    • rel-08/ralph-code-removal-summary.md

Progress File Format

JSONL (one JSON object per line):

{"iteration":1,"timestamp":"2026-01-11T08:37:27-06:00","progress":"Removed tool_dispatcher.c from Makefile"}
{"iteration":2,"timestamp":"2026-01-11T08:42:49-06:00","progress":"Deleted src/tool_bash.c and updated headers"}
{"iteration":3,"timestamp":"2026-01-11T08:51:20-06:00","progress":"DONE"}

Fields:

  • iteration - Iteration number
  • timestamp - ISO 8601 timestamp
  • progress - What was accomplished or DONE when complete

Summary File

Auto-generated markdown summarizing progress. Updated every 10 iterations by a summarizer agent. Provides condensed context for the worker agent without loading full history.

Loop Behavior

  1. Validate - Ensure goal file has ## Objective section
  2. Initialize - Create empty progress/summary files (or load if --continue)
  3. Handle dirty state - If working copy has changes, commit them
  4. Work iteration - Agent reads goal + history, makes progress, returns progress string
  5. Commit - Changes committed via jj commit
  6. Record - Progress appended to progress file
  7. Summarize - Every 10 iterations, summarizer condenses history
  8. Repeat - Until DONE returned or time expires

Termination:

  • Agent returns DONE
  • Time budget expires
  • Manual interrupt (Ctrl+C)

Writing Goals

State the objective clearly:

  • Good: "Remove all internal tool implementation code. After completion, tool calls return stub responses."
  • Bad: "Clean up the tool system"

Include acceptance criteria:

  • Good: "check-build → {\"ok\": true}"
  • Bad: "Tests should pass"

Reference detailed specs:

  • Good: "rel-08/plan/removal-specification.md - detailed spec with exact changes"
  • Bad: Inline the entire spec in the goal file

List concrete outcomes:

  • Good: "src/repl_tool.c - tool dispatch returns stub error JSON"
  • Bad: "Tool dispatch should be stubbed out"

Tips

  • Start with generous time budget - ralph may need multiple iterations
  • Use --continue to resume after interruption
  • Check progress file to see what's been accomplished
  • Goal files should be outcome-focused, not action-focused
  • Trust the agent to discover implementation details