Three small documentation fixes from the code review in #27.
1. README: "permanent cache hit" wording
Current: "Composes Block 1 once at startup — permanent cache hit"
This is ambiguous — it sounds like the provider's KV cache is guaranteed to hit, which is not true. What is actually permanent is Spore's local memoization of the rendered ComposedPrompt.
Fix: "Rendered once at startup and memoized — Block 1 never recomputed"
2. README: Quick Start disclaimer clarity
The Quick Start shows working Rust and TypeScript code with a small note: "Spore is in active design and pre-implementation. The interfaces below represent the target API."
The note is present but visually subordinate to the code. Someone skimming will try to cargo add spore-core and get nothing.
Fix: Make the pre-implementation status more prominent in the Quick Start section heading or use a callout block. The interfaces are the target API — that should be clear before the code, not after.
3. Spec: Ralph loop worked example
The spec defines Ralph as: "continues until external completion check passes" with Layer 1 BudgetExceeded as the hard stop.
The reviewer correctly noted that turn-budget intuitions are misleading for a continuation loop — a Ralph loop that resets context windows counts each window's turns separately against what budget?
Fix: Add a worked example to the Ralph loop strategy section showing:
- How max_turns budget applies per-task (total across all context windows, not per window)
- What happens when
BudgetExceeded fires mid-continuation
- How to size budgets for multi-context-window tasks
Related Issues
Three small documentation fixes from the code review in #27.
1. README: "permanent cache hit" wording
Current: "Composes Block 1 once at startup — permanent cache hit"
This is ambiguous — it sounds like the provider's KV cache is guaranteed to hit, which is not true. What is actually permanent is Spore's local memoization of the rendered
ComposedPrompt.Fix: "Rendered once at startup and memoized — Block 1 never recomputed"
2. README: Quick Start disclaimer clarity
The Quick Start shows working Rust and TypeScript code with a small note: "Spore is in active design and pre-implementation. The interfaces below represent the target API."
The note is present but visually subordinate to the code. Someone skimming will try to
cargo add spore-coreand get nothing.Fix: Make the pre-implementation status more prominent in the Quick Start section heading or use a callout block. The interfaces are the target API — that should be clear before the code, not after.
3. Spec: Ralph loop worked example
The spec defines Ralph as: "continues until external completion check passes" with Layer 1
BudgetExceededas the hard stop.The reviewer correctly noted that turn-budget intuitions are misleading for a continuation loop — a Ralph loop that resets context windows counts each window's turns separately against what budget?
Fix: Add a worked example to the Ralph loop strategy section showing:
BudgetExceededfires mid-continuationRelated Issues