Content
87%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.
An efficient, highly actionable body with executable commands throughout, a proper validation gate on the environment check, and exemplary progressive disclosure of setup details into references/setup.md. The main gap is the batch-generation workflow, which lacks any post-run verification or failure-recovery step, capping workflow clarity at 3.
Suggestions
Add a validation step after batch generation, e.g. 'After run jobs completes, check report.json for failed jobs (jq '.jobs[] | select(.status != "success")') and re-run failed entries — run jobs skips already-succeeded jobs via --state-file'.
State what a failed export or generation looks like (error exit code, JSON error shape) and what to do about it, so the end-to-end workflow has a recovery loop for its async tasks.
Clarify in the batch section whether --state-file makes re-runs idempotent, so an agent knows it can safely retry the whole file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and every token earns its place: all sections are runnable commands or operational facts Claude cannot know ('accept short prefixes (like git short hashes)', "--pages is a hint to the AI", 'Progress lines go to stderr (format: [PROGRESS] ...)', 'Config priority: CLI args > env vars > TOML'). No concept explanations or padding, so it does not fall to 4. | 5 / 5 |
Actionability | Everything is copy-paste executable: a complete end-to-end workflow (create project via --json + jq, set working project, run full workflow, export), batch generation with a concrete jobs.jsonl heredoc, renovation command, and JSON piping examples. Specific examples cover the common cases, matching the top anchor. | 5 / 5 |
Workflow Clarity | The main workflow is clearly sequenced and gated by an explicit health check ('Do not proceed until the health check passes'), but the batch-generation workflow ('banana-cli run jobs --file jobs.jsonl --report report.json') is a batch operation with no validation/verification step — nothing instructs checking report.json for failed jobs or retrying them. Per the rubric, missing validation in batch operations caps workflow clarity at 3. | 3 / 5 |
Progressive Disclosure | The body is a concise overview with a single clearly-signaled, one-level-deep reference ('Read [references/setup.md](references/setup.md)') that exists as a real bundle file containing the offloaded setup steps; there is no inlined content that belongs in a separate file and no nested references. This matches the actual bundle structure, not just the reference links. | 5 / 5 |
Total | 18 / 20 Passed |