/ralph-docs

name: ralph-docs
description: Introspect, explain, and improve Ralph Orchestrator using its published llms.txt doc map. Use this skill whenever the user asks questions about Ralph's behavior, wants to understand how a Ralph internal works (event loop, hats, memories, tasks, backends, presets), debug an unfamiliar failure mode, or propose a code change to the ralph-orchestrator repo. The skill teaches the agent to discover authoritative answers from the live docs via llms.txt before guessing, and to scope improvements through the published architecture rather than the local checkout alone.

Ralph Docs

Introspect Ralph Orchestrator the same way the framework expects a smart agent to — consult the published documentation map at <https://mikeyobrien.github.io/ralph-orchestrator/llms.txt>, fetch only the sections relevant to the question, and answer from authoritative sources.

Use this skill to behave like an internal Ralph contributor rather than a guess-first assistant.

Use This Skill For

• Answering "how does Ralph do X?" questions about the event loop, hats,

memories, tasks, presets, backends, CLI, TUI, diagnostics, waves, or API.

• Explaining an observed behavior ("why did my loop terminate with

max_iterations?", "why didn't my hat fire?") from first principles in the docs, not pattern-matching.

• Proposing and scoping an improvement to the `ralph-orchestrator` codebase —

locating the right crate, the relevant concept doc, and the existing test surface before writing code.

• Triaging a ralph bug report: map symptoms to likely subsystem, pull in the

concept + reference docs for that subsystem, identify the probable file path in the repo.

• Onboarding: answer a new user's setup/quick-start questions from the official

Getting Started pages instead of the agent's stale training data.

Core Principle: llms.txt Is The Router

Ralph's llms.txt is a curated map, not a full-text dump. The workflow is:

1. **Discover** — fetch `llms.txt` to see the top-level sections (Getting Started / Concepts / User Guide / Advanced / API / Examples / Contributing / Reference). 2. **Narrow** — pick the 1–3 pages that actually answer the question. The map links directly to `.md` versions — those are agent-optimized and should be preferred over scraping HTML. 3. **Fetch** — pull only those pages. Do not fetch more than three pages speculatively; the budget should be spent on answering, not browsing. 4. **Cross-check** — for code-level claims, confirm against the repo (crate paths are listed in AGENTS.md / CLAUDE.md inside the ralph-orchestrator checkout). 5. **Answer** — cite the page you relied on. Include the URL so the user can verify.

Workflow

1. Identify the question's subsystem using the taxonomy in `references/llms-txt-map.md` (hats, event loop, memories, tasks, backends, presets, CLI, TUI, diagnostics, waves, API). 2. If `~/.cache/ralph-docs/llms.txt` exists and is <7 days old, use it. Else refetch it:

   mkdir -p ~/.cache/ralph-docs
   curl -sSfL https://mikeyobrien.github.io/ralph-orchestrator/llms.txt \
     -o ~/.cache/ralph-docs/llms.txt

3. Pick the 1–3 linked `.md` pages most relevant to the subsystem. The map entries are documented in `references/llms-txt-map.md`; use it to shortcut the grep. 4. Fetch just those pages via `curl -sSfL <url> -o ~/.cache/ralph-docs/<stem>.md` and read them. Agents with `web_fetch` or an equivalent tool should use that instead. 5. Answer the user's question grounded in what you just read. Quote the relevant sentence when the user asks "does Ralph do X?" so they can audit. 6. If the answer requires a code change, switch to the ralph-orchestrator checkout and follow `references/contributing.md` for the propose-a-change workflow.

Scope Boundaries

• This skill answers and explains. For creating/modifying user hats, defer to

**ralph-hats**. For operating a live loop (running, resuming, merging, debugging), defer to **ralph-loop**. For code changes to ralph-orchestrator itself, this skill scopes the change; the actual editing uses the agent's native code-editing tools.

• Do not invent features not present in the published docs. If llms.txt does

not surface an answer, say so and suggest checking the source tree at <https://github.com/mikeyobrien/ralph-orchestrator>.

• Do not rely on the agent's pretraining for version-sensitive claims (e.g.

CLI flags, preset names). Ralph's CLI evolves; always verify against `guide/cli-reference.md` or `reference/changelog.md`.

Guardrails

• Prefer `.md` URLs from llms.txt over scraping the rendered HTML.
• Cache fetched pages under `~/.cache/ralph-docs/` with a 7-day staleness

threshold. Refetch llms.txt before any other doc to detect renames/moves.

• When cited docs contradict the local checkout (docs newer than the user's

installed ralph version), note the mismatch and suggest `ralph --version` so the user can decide which to trust.

• For "how to improve Ralph" requests, always read

`concepts/tenets/index.md` first. Ralph's six tenets are load-bearing; changes that fight them usually belong somewhere else.

Output Expectations

• Answer first, then link. Don't make the user wait for a verbose tour.
• Include at least one source URL for non-trivial claims.
• When proposing a code change, name the crate + file (see

`references/contributing.md` for the crate map), the concept doc that justifies the change, and the test file that should cover it.

Read These References When Needed

• For the llms.txt section map + which pages answer which question:

`references/llms-txt-map.md`

• For FAQ recipes (common introspection patterns):

`references/common-questions.md`

• For how to propose a code change, including crate layout and PR conventions:

`references/contributing.md`