Content
40%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.
The body is rich in concrete, executable POSIX-sh snippets but is undermined by heavy redundancy, restated basics, no sequenced workflow with validation, and a monolithic inline structure with a dangling reference.
Suggestions
De-duplicate guidance repeated across sections (POSIX Constraints, Approach, Common Pitfalls, POSIX-Specific Best Practices) into a single canonical list to cut tokens.
Add an explicit numbered workflow with validation checkpoints for destructive operations (e.g. lint with shellcheck -s sh -> test on dash/ash -> validate output), instead of only generic instructions.
Move the Essential Tools catalog and References links into separate reference files and fix or remove the dangling 'resources/implementation-playbook.md' pointer (note: the directory is 'resources/', not the conventional 'references/').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~300-line body is a padded wall of bullets restating POSIX basics Claude already knows, with heavy redundancy ('use [ not [[' and 'quote variable expansions' each repeated across POSIX Constraints, Approach, Common Pitfalls, and POSIX-Specific Best Practices), fitting the 'noticeably verbose, several padded sections' anchor. | 2 / 5 |
Actionability | Many concrete executable fragments ('trap 'rm -f "$tmpfile"' EXIT INT TERM', 'command -v cmd >/dev/null 2>&1', 'set -- item1 item2 item3') provide mostly copy-paste-ready guidance, with minor gaps since most are fragments rather than complete scripts. | 4 / 5 |
Workflow Clarity | No real sequenced workflow exists; the 'Instructions' section is generic ('Apply relevant best practices and validate outcomes') and destructive operations (rm -rf) lack explicit validation checkpoints, so it sits at the 'rough sequence, validation absent' anchor and is capped at 3 by the destructive-operations rule. | 2 / 5 |
Progressive Disclosure | No bundle files exist, yet the body inlines content that belongs in separate files (Essential Tools catalog, References & Further Reading) and its sole external reference 'resources/implementation-playbook.md' points to a non-existent file, fitting the 'content that belongs in separate files is inlined' anchor. | 2 / 5 |
Total | 10 / 20 Passed |