Content
88%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 highly actionable, well-sequenced procedural skill whose workflow and validation design are excellent. The main improvements are trimming the advisory/duplicative sections and splitting the large template and example into reference files to reduce context load.
Suggestions
Move the full ralph-plan template and the worked example transformation into references/ (e.g., references/template.md and references/example.md), keeping SKILL.md as an overview that links to them — this would shrink the always-loaded body substantially.
Cut the 'When to Use' section (it duplicates the frontmatter description) and drop or compress 'Tips for Success' items that address the user rather than the executor, such as 'Monitor the first few iterations'.
Specify how the [timestamp] in '.claude/ralph-plans/[timestamp]-ralph-plan.md' should be generated (e.g., date +%Y%m%d-%H%M%S) so the output path is fully deterministic.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The bulk is lean operational content (executable steps, a template, a worked example) with no explanation of concepts Claude already knows, but a few sections could be trimmed: 'When to Use' restates the frontmatter description and 'Tips for Success' ('The better the input plan, the better the ralph execution', 'Monitor the first few iterations') is dispensable advice. This sits at 'efficient with minor over-explanation' rather than the mostly-efficient-with-notable-padding level below. | 4 / 5 |
Actionability | Fully executable guidance throughout: 'ls -t ~/.claude/plans/*.md | head -1', the complete '/ralph-loop "..." --max-iterations 50 --completion-promise "COMPLETE"' invocation, a full transformation template, and a worked example with real file paths and runnable commands (pytest tests/test_auth.py -v, curl -X POST ..., ruff check src/). The template's bracketed placeholders are justified flexibility for a transformation target, and the concrete example covers the common case. | 5 / 5 |
Workflow Clarity | Four clearly sequenced steps (find plan, parse, transform, execute) with explicit validation built in: per-phase verification commands in the template, a completion checklist, an escape hatch after 40 iterations emitting <promise>BLOCKED</promise>, and rollback guidance. This matches the top anchor — clear sequence, explicit validation steps, feedback loops, and checklists. | 5 / 5 |
Progressive Disclosure | The single file is well-sectioned with clear headers and everything is one level deep, but at ~215 lines the full ralph-plan template (~75 lines) and the example transformation (~45 lines) are natural candidates for references/ files. Good structure with minor organization gaps rather than the appropriately-split, reference-linked layout of the top anchor. | 4 / 5 |
Total | 18 / 20 Passed |