Content
75%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 lean, highly actionable authoring guide that assumes competence and concentrates Crush-specific gotchas (exit 49 halt semantics, shallow-merge updated_input, config-order aggregation, silent timeout kills) into copy-paste-ready examples. The defects are minor and specific: a placeholder in the rewrite example, no explicit hook-testing step in the workflow, a dangling docs reference with no bundle split, and a couple of points stated twice. It sits solidly at the 4 anchor on every dimension — noticeably above midpoint but short of each 5 anchor's bar.
Suggestions
Add a validation step to the Authoring Checklist (e.g. "Test: pipe a sample PreToolUse JSON payload into the script and confirm the exit code / envelope before relying on it") to close the workflow-clarity gap.
Make the rewrite example fully executable by replacing `some-rewriter` with a concrete transformation, or explicitly flag it as a placeholder for the user's rewriter.
Ship `docs/hooks/README.md` in the bundle (or cite Crush's external docs URL), and consider moving the 13-event list plus per-event payload extras into that reference file; also de-duplicate the sub-agent and Claude-Code-compatibility remarks that appear in both the opening/Input sections and later sections.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Dense and assumes competence — no explanations of hooks-in-general, regex, or JSON (e.g. "updated_input: shallow-merge patch against tool_input, not a replacement"). Minor trimmable redundancy keeps it below the 5 anchor ("every token earns its place"): the sub-agent rule is stated twice ("sub-agent calls (task tool, agentic_fetch, etc.) are not intercepted" and "Turn and tool events fire only for the top-level agent, never for sub-agents"), and Claude-Code compatibility is previewed in Input ("scripts written for Claude Code usually work unchanged") then restated in its own closing section. | 4 / 5 |
Actionability | Nearly everything is copy-paste ready: the no-rm-rf.sh blocker ("grep -qE 'rm\s+-(rf|fr)\s+/'"), the inline auto-approver ("echo '{\"decision\":\"allow\"}'"), the go-context.sh injector, and the jq redaction one-liner. One example is not executable as written — "rewritten=$(jq -r '.tool_input.command' | some-rewriter)" uses an unjustified placeholder — which fits 4 ("minor gaps") rather than 5 ("fully executable"), and the rubric penalizes pseudocode unless flexibility is explicitly justified. | 4 / 5 |
Workflow Clarity | The Authoring Checklist gives a clear 5-step sequence (shebang/set, chmod +x, crush.json entry with matcher, decide intent, remember shallow-merge) and Debugging supplies error-recovery guidance ("Timeouts kill the hook silently", "Non-zero exit codes other than 2/49 are logged but don't block — check Crush logs"). No explicit validation step exists — there is no "test the hook with a sample stdin payload" checkpoint — so it lands at 4 rather than 5's "explicit validation steps; feedback loops"; the destructive-operation cap does not apply since authoring a hook is itself non-destructive. | 4 / 5 |
Progressive Disclosure | Well-sectioned single-file guide with one clearly signaled one-level reference ("For the full reference, see docs/hooks/README.md"), but the bundle contains no reference files, so that path is dangling and cannot be loaded. Reference-grade detail (the 13-event list and per-event payload extras) is inlined rather than split out. Good structure with minor organization gaps matches 4; not 5 because content is not actually split across bundle files. | 4 / 5 |
Total | 16 / 20 Passed |