[GH-ISSUE #174] [Feature]: Add configuration option to disable scratchpad injection and instructions

kerem commented

2026-02-27 10:22:03 +03:00

Owner

Originally created by @luisherranz on GitHub (Feb 13, 2026).
Original GitHub issue: https://github.com/mikeyobrien/ralph-orchestrator/issues/174

Use case

Currently, the scratchpad (.ralph/agent/scratchpad.md) is unconditionally injected into every agent's prompt on every iteration, and the ### 0b. SCRATCHPAD instructions section telling agents to write to it is always present. There is no way to disable this behavior.

This is problematic in multi-hat configurations for several scenarios:

1. Adversarial HAT configurations

In setups where HATs are intentionally adversarial (e.g., a Builder and a Confessor that evaluates the Builder's honesty), the Confessor can read the Builder's reasoning in the scratchpad, which defeats the purpose of an independent evaluation. The scratchpad leaks the internal reasoning of one agent to another, potentially biasing their output.

2. Phase-separated workflows with independent state

When HATs are designed to operate in distinct phases (e.g., Design → Implementation → Review), each phase may manage its own structured files in .ralph/agent/ for state persistence. In these cases:

The design HAT might write to .ralph/agent/design-notes.md
The implementation HAT might write to .ralph/agent/implementation-log.md
The review HAT might write to .ralph/agent/review-findings.md

The shared scratchpad becomes noise — polluting each phase with irrelevant context from previous phases. Once the design phase is finished and implementation begins, there's no need to read what the design HATs wrote in the scratchpad, especially if the relevant output is already captured in purpose-built files.

3. Token efficiency

The scratchpad budget is 16,000 characters (~4,000 tokens) of content injected into every prompt. For HATs that don't need cross-iteration continuity via the scratchpad (because they use other mechanisms), this is wasted context window.

Proposed solution

Add a configuration option to core in ralph.yml to disable the scratchpad:

core:
  scratchpad: ".ralph/agent/scratchpad.md"
  scratchpad_inject: false  # default: true

When scratchpad_inject is set to false:

Skip scratchpad file injection — prepend_scratchpad() in EventLoop should return the prompt unchanged.
Skip the ### 0b. SCRATCHPAD instructions section — core_prompt() in HatlessRalph should omit the section that tells agents to write to the scratchpad. Injecting instructions to write to a file that won't be read back makes no sense and wastes tokens.
Skip scratchpad references in ### STATE MANAGEMENT — The state management guidance should not reference the scratchpad when it's disabled.
Skip scratchpad references in ## WORKFLOW — Workflow steps like "update scratchpad" should be omitted or adapted.

The ## ORIENTATION section, guardrails, and other core prompt sections should remain unaffected.

Area

Other

Backend(s) impacted

No response

Alternatives considered

No response

Additional context

In solo mode (no hats defined), the scratchpad is the primary continuity mechanism between iterations. Since each iteration starts with completely fresh context and there are no alternative state channels (events are routing signals, not narrative state), disabling the scratchpad in solo mode would effectively break the agent's ability to maintain state.

The implementation should either:

Ignore scratchpad_inject: false in solo mode and log a warning, or
Document clearly that this option is intended for multi-hat configurations where hats manage their own state files

Originally created by @luisherranz on GitHub (Feb 13, 2026). Original GitHub issue: https://github.com/mikeyobrien/ralph-orchestrator/issues/174 ### Use case Currently, the scratchpad (`.ralph/agent/scratchpad.md`) is unconditionally injected into every agent's prompt on every iteration, and the `### 0b. SCRATCHPAD` instructions section telling agents to write to it is always present. There is no way to disable this behavior. This is problematic in multi-hat configurations for several scenarios: ### 1. Adversarial HAT configurations In setups where HATs are intentionally adversarial (e.g., a Builder and a Confessor that evaluates the Builder's honesty), the Confessor can read the Builder's reasoning in the scratchpad, which defeats the purpose of an independent evaluation. The scratchpad leaks the internal reasoning of one agent to another, potentially biasing their output. ### 2. Phase-separated workflows with independent state When HATs are designed to operate in distinct phases (e.g., Design → Implementation → Review), each phase may manage its own structured files in `.ralph/agent/` for state persistence. In these cases: - The design HAT might write to `.ralph/agent/design-notes.md` - The implementation HAT might write to `.ralph/agent/implementation-log.md` - The review HAT might write to `.ralph/agent/review-findings.md` The shared scratchpad becomes noise — polluting each phase with irrelevant context from previous phases. Once the design phase is finished and implementation begins, there's no need to read what the design HATs wrote in the scratchpad, especially if the relevant output is already captured in purpose-built files. ### 3. Token efficiency The scratchpad budget is 16,000 characters (~4,000 tokens) of content injected into every prompt. For HATs that don't need cross-iteration continuity via the scratchpad (because they use other mechanisms), this is wasted context window. ### Proposed solution Add a configuration option to `core` in `ralph.yml` to disable the scratchpad: ```yaml core: scratchpad: ".ralph/agent/scratchpad.md" scratchpad_inject: false # default: true ``` When `scratchpad_inject` is set to `false`: 1. **Skip scratchpad file injection** — `prepend_scratchpad()` in `EventLoop` should return the prompt unchanged. 2. **Skip the `### 0b. SCRATCHPAD` instructions section** — `core_prompt()` in `HatlessRalph` should omit the section that tells agents to write to the scratchpad. Injecting instructions to write to a file that won't be read back makes no sense and wastes tokens. 3. **Skip scratchpad references in `### STATE MANAGEMENT`** — The state management guidance should not reference the scratchpad when it's disabled. 4. **Skip scratchpad references in `## WORKFLOW`** — Workflow steps like "update scratchpad" should be omitted or adapted. The `## ORIENTATION` section, guardrails, and other core prompt sections should remain unaffected. ### Area Other ### Backend(s) impacted _No response_ ### Alternatives considered _No response_ ### Additional context In solo mode (no hats defined), the scratchpad is the **primary continuity mechanism** between iterations. Since each iteration starts with completely fresh context and there are no alternative state channels (events are routing signals, not narrative state), disabling the scratchpad in solo mode would effectively break the agent's ability to maintain state. The implementation should either: - **Ignore `scratchpad_inject: false` in solo mode** and log a warning, or - **Document clearly** that this option is intended for multi-hat configurations where hats manage their own state files

kerem added the

enhancement

label

2026-02-27 10:22:03 +03:00

kerem commented

2026-02-27 10:22:04 +03:00

Author

Owner

@luisherranz commented on GitHub (Feb 13, 2026):

I'd be happy to send a PR if this functionality were accepted.

@luisherranz commented on GitHub (Feb 13, 2026): I'd be happy to send a PR if this functionality were accepted.

kerem commented

2026-02-27 10:22:04 +03:00

Author

Owner

@mikeyobrien commented on GitHub (Feb 13, 2026):

I’d prefer scratchpad config per hat, with global fallback.

Something like this:

core:
  scratchpad:
    enabled: true
    path: .ralph/agent/scratchpad.md

hats:
  planner:
    scratchpad:
      path: .ralph/agent/planner.md

  builder:
    scratchpad:
      path: .ralph/agent/builder.md

  validator:
    scratchpad:
      enabled: false

Resolution order per hat run:

hat scratchpad config
global core scratchpad config
current default

This keeps backward compatibility, avoids cross-hat leakage, and still preserves continuity where needed.

@mikeyobrien commented on GitHub (Feb 13, 2026): I’d prefer scratchpad config per hat, with global fallback. Something like this: ```yaml core: scratchpad: enabled: true path: .ralph/agent/scratchpad.md hats: planner: scratchpad: path: .ralph/agent/planner.md builder: scratchpad: path: .ralph/agent/builder.md validator: scratchpad: enabled: false ``` Resolution order per hat run: 1) hat scratchpad config 2) global core scratchpad config 3) current default This keeps backward compatibility, avoids cross-hat leakage, and still preserves continuity where needed.

kerem commented

2026-02-27 10:22:04 +03:00

Author

Owner

@mikeyobrien commented on GitHub (Feb 13, 2026):

When I transitioned from scratchpad to the memory/task tool system, it caused a lot of undesirable side-effects and I readded it.

@mikeyobrien commented on GitHub (Feb 13, 2026): When I transitioned from scratchpad to the memory/task tool system, it caused a lot of undesirable side-effects and I readded it.

kerem commented

2026-02-27 10:22:04 +03:00

Author

Owner

@luisherranz commented on GitHub (Feb 14, 2026):

Makes sense.

I will make a PR and try it myself to see how it works on those cases, thanks.

@luisherranz commented on GitHub (Feb 14, 2026): Makes sense. I will make a PR and try it myself to see how it works on those cases, thanks.

kerem commented

2026-02-27 10:22:04 +03:00

Author

Owner

@luisherranz commented on GitHub (Feb 24, 2026):

I have opened a draft PR with an initial implementation proposal. I'll test it locally to see how it works.

https://github.com/mikeyobrien/ralph-orchestrator/pull/186

@luisherranz commented on GitHub (Feb 24, 2026): I have opened a draft PR with an initial implementation proposal. I'll test it locally to see how it works. - https://github.com/mikeyobrien/ralph-orchestrator/pull/186

kerem referenced this issue

2026-02-27 10:22:17 +03:00

[PR #67] [MERGED] feat(adapters): add OpenCode CLI backend support #116

Rows
Columns

[GH-ISSUE #174] [Feature]: Add configuration option to disable scratchpad injection and instructions #67

Use case

1. Adversarial HAT configurations

2. Phase-separated workflows with independent state

3. Token efficiency

Proposed solution

Area

Backend(s) impacted

Alternatives considered

Additional context