Content
81%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 highly actionable and workflow-safe, with copy-paste commands, explicit dry-run/validation loops for destructive operations, and a verified one-level-deep reference bundle. Its main weakness is token efficiency: a near-duplicated exit-code section and dense inline enumerations that belong in the already-provided reference files keep it from being lean.
Suggestions
Remove the duplicated exit-code explanation (Agent Rule 2 vs the Exit Codes section) by keeping one canonical statement and pointing the other to `fallow schema.exit_codes`.
Move the flags-retirement reason-code enumeration and per-format rule IDs (SARIF/CodeClimate) into references/cli-reference.md, keeping only the core commands and the advisory-no-autofix caveat inline.
Trim the suppression-comment semantics detail in the Issue Types section to the two comment forms and defer placement/reason rules to references/issue-types.md, which already catalogues them.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with fallow-specific facts and contains no generic conceptual padding, but it could be tightened: the exit-code semantics paragraph appears nearly verbatim twice (Agent Rule 2 and the Exit Codes section), and inline enumerations such as every flags-retirement reason code and the SARIF/CodeClimate rule IDs exceed what the body needs. This is "mostly efficient but includes some unnecessary explanation or could be tightened" rather than anchor 4's "minor instances". | 3 / 5 |
Actionability | Nearly every section provides copy-paste-ready commands with exact flags (e.g. `fallow dead-code --format json --quiet --unused-exports`, the full fix dry-run/apply/verify cycle), a concrete JSON judgment example, and exact suppression-comment syntax. Specific executable examples cover the common cases, matching anchor 5. | 5 / 5 |
Workflow Clarity | Multi-step processes are clearly sequenced with explicit validation: the task-matrix routes intents to commands, `fallow doctor` serves as a preflight, the destructive `fix` workflow mandates `--dry-run` preview then verification via a follow-up `dead-code` run, and the audit walkthrough includes stale-hash recovery ("On `stale: true`, fetch the guide again"). The destructive-operation validation cap does not apply because validation checkpoints are explicit. | 5 / 5 |
Progressive Disclosure | Seven real, one-level-deep reference files (cli-reference, mcp, issue-types, gotchas, patterns, similar-code, node-bindings — all verified to exist) are clearly listed with one-line descriptions, and bulk catalogues are correctly externalized. However, some heavy detail remains inline that duplicates the references, such as the full flags-retirement reason enumeration and suppression semantics paragraphs, which is a minor organization gap against anchor 5's "content appropriately split". | 4 / 5 |
Total | 17 / 20 Passed |