Description:

The agents.md/claude.md instructions contain an abstraction leak: they're written from the perspective of someone who understands Ralph orchestration loop, not from the perspective of the agent executing inside it.

The problem:

The agent running inside a session has no knowledge of:

• The outer bash loop invoking it
• That other sessions exist or will follow
• What an "iteration" is
• That it's one of N invocations

But the instructions reference these concepts as if the agent understands them.

Examples of abstraction leaks:

1. "Iteration" terminology
   - Instructions say "Work on ONE story per iteration"
   - Agent doesn't know what an "iteration" is—it only knows "session"
   - Should say "per session"
2. References to other iterations
   - "Another iteration will pick up the next story"
   - "Future iterations should know..."
   - Agent can't reason about things it has no concept of
3. Vague completion criteria
   - "End your response normally"
   - What's "normal" to an agent with no context about the loop?
   - Should explicitly state: "end after completing steps 1-12"
4. Implicit assumptions
   - Instructions assume the agent understands its output won't persist
   - Instructions assume the agent knows WHY it should document learnings
   - These assumptions should be made explicit

The fix:

Write all instructions as if you're talking to an agent that:

• Knows only what's in the instructions file
• Has no concept of an outer loop or other sessions
• Needs explicit definitions of "done", "complete", "normally"
• Needs to be told exactly when to stop and what constitutes success

Recommended changes:

1. Replace "iteration" → "session" throughout
2. Remove references to "other iterations" or "future iterations" → use "future sessions" and explain that sessions
   don't share memory
3. Define completion explicitly: "A story is NOT complete until you have: implemented code, passed checks, committed,
   and set passes: true"
4. Reference step numbers in stop conditions: "end your session after completing steps 1-12"
5. State explicitly: "Each session starts fresh with no memory of previous sessions"

General principle:

The orchestrator (ralph.sh) and the agent (reading agents.md) operate at different levels of abstraction. Instructions
meant for the agent should never assume knowledge that only the orchestrator has.