Content
73%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 — exact commands, flags, exit semantics, examples, and output format — with a clear empty-result feedback loop. Its main weakness is redundancy: three core rules (search first, never fabricate, use noun phrases) are each restated across Mindset, Never, a duplicate second Mindset, and Anti-Patterns sections, inflating token cost without adding information.
Suggestions
Delete the duplicate '## Mindset' section (lines 76-78) — it restates the opening Mindset and Never rules verbatim in spirit.
Merge '## Never' and '## Anti-Patterns' into a single section; both cover the same three rules (search before implementing, never fabricate results, never query with full sentences), so one canonical statement suffices.
Deduplicate '## Query construction' against references/query-tips.md — move the noun-phrase and broadening detail fully into the reference and keep only a one-line pointer in the body, so the split is clean rather than overlapping.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body repeats each core rule two to three times: a literal duplicate '## Mindset' section appears at both the top and bottom, the '## Never' section restates Mindset and Query construction rules, and '## Anti-Patterns' restates 'Never' and 'Handling no results' almost verbatim. This is 'noticeably verbose; several unnecessary… padded sections' (anchor 2) — not 3, because roughly a third of the sections are pure restatement rather than isolated tightening opportunities. | 2 / 5 |
Actionability | Fully executable, copy-paste-ready guidance: exact CLI syntax with flags ('vault-cli search "<query>" [--top-k <n>] [--project <id>]'), explicit exit behavior ('Exits 1 with "No results."'), four concrete example commands covering plain, project-scoped, top-k, and error-message queries, plus a sample output format. Matches anchor 5: examples cover the common cases. | 5 / 5 |
Workflow Clarity | The workflow is clearly sequenced with an explicit feedback loop: construct a noun-phrase query → run the search → on empty, 'Retry with a broader synonym query' → if still empty, report honestly and 'Never invent or guess at a prior decision'. The exit-1/'No results.' signal serves as the validation checkpoint, matching anchor 5's 'feedback loops for error recovery'; this is a non-destructive single-command skill so no validation cap applies. | 5 / 5 |
Progressive Disclosure | Good structure with a well-signaled, one-level-deep reference ('[Vault Search: Query Tips](references/query-tips.md)' — a real file) and clear section headers. Not 5: the duplicate '## Mindset' section and the overlap between the body's 'Query construction' section and the reference file's content ('Use concrete nouns from the task, not the literal user phrasing' appears in both) are minor organization gaps — anchor 4's 'most content is appropriately placed' with 'minor organization gaps'. | 4 / 5 |
Total | 16 / 20 Passed |