Content
63%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured, mostly lean skill body with clear phase sequencing, good reference linking, and concrete templates for specs, state, and spawn prompts. The main weaknesses are the pseudocode (rather than executable) orchestrator loop, an unlinked helper script in the bundle, and body references to stacks/ files that don't ship with the bundle.
Suggestions
Surface `scripts/ralph-state.sh` from the body (e.g. 'Initialize state: `scripts/ralph-state.sh init <task> <project_dir>`') — and note the script's header advertises `step`/`complete`/`done` commands that its case statement doesn't implement, so either implement them or fix the usage comment.
Replace the Phase 4 orchestrator pseudocode with an executable loop, or explicitly justify the pseudocode (e.g. because `sessions_spawn` invocation is host-specific) and link to `references/ralph-pattern.md` for runnable details.
Remove the hardcoded 'Available stacks' list (or mark it as dynamically read from `stacks/`), and either ship the referenced `stacks/*.md` files in the bundle or state that they are created on first use, so no body path dangles.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and nearly every section earns its tokens: JSON schemas for `.spec.json` and `.ralph-state.json`, a verbatim spawn prompt, a stack-file template, and a quick-reference table. Only minor instances could be trimmed — the 'Why Ralph?' rationale about context degradation (something Claude already knows), the 'This is the key differentiator' motivational sentence, and the orchestrator pseudocode that duplicates the numbered list above it. This is 'efficient; minor instances of over-explanation', not the noticeably-verbose anchor 3. | 4 / 5 |
Actionability | Discovery, stack matching, and planning give concrete, executable guidance, but the core Phase 4 orchestrator loop is explicitly labeled 'Pseudocode — main session runs this' with no justification for why it isn't executable, and the bundled helper script `scripts/ralph-state.sh` (which implements init/show/reset for exactly this state file) is never mentioned, so the reader can't run state management as-is. 'Pseudocode instead of executable code; missing key details' fits better than anchor 4's 'concrete code with minor gaps'. | 3 / 5 |
Workflow Clarity | The four phases are clearly sequenced with inputs and outputs summarized in the Quick Reference table, and checkpoints are mostly explicit: 'Confirm spec with user before proceeding' in Phase 1, and the spawn prompt's rule 'Set status to "completed" only when everything builds and works' plus the max-iteration guard. The gap keeping it below 5 is that the orchestrator loop itself has no verify step — validation is delegated entirely to the spawned iteration's self-reported status. | 4 / 5 |
Progressive Disclosure | The three reference files (agents-template.md, execution-rules.md, ralph-pattern.md) exist and are clearly signaled one level deep with proper links, but the bundle structure is misaligned in both directions: `scripts/ralph-state.sh` ships in the bundle yet is never referenced from the body (orphaned, undiscoverable), and the body points to a `stacks/` directory and stack files (`cloudflare-hono.md`, `go-cli.md`) that are not present in the bundle. The hardcoded 'Available stacks' list marked '(read from stacks/ dir)' is also stale-prone. This is more than the 'minor organization gaps' of anchor 4. | 3 / 5 |
Total | 14 / 20 Passed |