Content
63%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 strong, largely executable command reference with good safety and validation guidance for destructive and batch operations. Its main weaknesses are inline reference-manual bulk (attachments, sync, recurring internals) that belongs in separate files, and the absence of one explicit end-to-end workflow tying the per-topic guidance together.
Suggestions
Move the attachment lifecycle, sync internals, and recurring-task grammar deep detail into one-level-deep reference files (e.g., references/attachments.md, references/recurring.md) linked from a concise SKILL.md overview.
Trim agent-irrelevant detail such as TUI keybindings (Tab/Enter/o) and full JSON field inventories, keeping only what an agent needs to issue commands and interpret output.
Add a short 'Typical workflow' section that sequences the existing pieces explicitly (e.g., list --ready -> context/show --full -> edit -> note) so the multi-step process is not left implicit.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense reference material with no re-teaching of known concepts, but sections like the attachment JSON field inventory ("attachment_id, task_id, sha256, byte_size, media_type, filename..."), sync transfer round limits ("up to 16 unique blobs and 64 MiB"), and TUI keybindings ("Tab focuses locally available images... Enter opens the large TUI preview") are detail that could be tightened or trimmed. It fits anchor 3 ('mostly efficient but could be tightened') rather than anchor 4 because several sections read as a product manual rather than agent instructions. | 3 / 5 |
Actionability | The command catalog is largely copy-paste ready ("aven add \"Fix conflict display\" --status todo --priority high --label bug", "aven edit APP-7KQ9 --due \"in 2 weeks\"") and covers common cases, matching anchor 4. It falls short of anchor 5 because a few commands appear only in prose without syntax examples (e.g., "Use bulk-update --dry-run before broad mutations", "blocked_by=[REFS]" in aven prime). | 4 / 5 |
Workflow Clarity | Validation checkpoints are explicit for risky operations ("Use bulk-update --dry-run before broad mutations", attachment prune --dry-run before --apply, "Inspect dependency context with show <ref> --full before changing task order or status"), satisfying the batch/destructive validation requirement. It is anchor 4 rather than 5 because the implied find -> inspect -> update -> handoff flow is never assembled into one explicit sequenced workflow; guidance is organized per-topic instead. | 4 / 5 |
Progressive Disclosure | The file has clear section headers and code blocks, but roughly 350 lines of reference-manual detail (attachment lifecycle internals, sync blob transfer mechanics, recurring-grammar rules, export/import invariants) that clearly belongs in separate reference files is inlined, and no bundle files exist to offload it. This matches anchor 3 ('some structure but content that should be separate is inline'), not anchor 2, because organization within the file is reasonable. | 3 / 5 |
Total | 14 / 20 Passed |