Content
32%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 reads as an auto-generated feature catalog: extensive and well-sectioned, but bloated, lacking any end-to-end workflow with validation, and riddled with corrupted URLs and dead references that break executability. It also embeds a duplicate YAML frontmatter block at the top of the body, indicating malformed document structure. Strongest aspects are the section organization and the density of concrete (if unverified) command examples.
Suggestions
Restructure around one or two end-to-end workflows (init → sync → verify) with explicit validation steps (e.g. `gh project item-list` to confirm sync state) before batch operations, and move the long command catalog to reference files.
Fix the corrupted URLs and paths ("https:/$api.example.com$github-sync", ".$swarm-issue.md") so snippets and cross-references actually resolve, and either create the referenced files or remove the links.
Cut low-value sections (Best Practices platitudes, Metrics & KPIs, duplicate near-identical command variants) to roughly a quarter of the current length, keeping one representative executable example per feature.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is ~470 lines: a catalog of dozens of `npx ruv-swarm github ...` command variants plus padded sections like "Best Practices" ("Clear column definitions", "Training materials") and "Metrics & KPIs" that add no actionable information. It is noticeably verbose with several padded sections (anchor 2); it avoids anchor 1 only because it doesn't lecture about concepts Claude already knows — the padding is redundant command listings and platitudes rather than tutorial prose. | 2 / 5 |
Actionability | Commands are concrete and specific (e.g. `gh project list --owner @me --format json | jq ...`, `npx ruv-swarm github board-sync --auto-move-cards --update-metadata`), but many snippets are not executable as written: corrupted URLs ("https:/$api.example.com$github-sync", "https:/$github.com$GITHUB_REPOSITORY$issues/$issue"), `$PROJECT_ID` used in later sections without being defined, and a long tail of unverifiable ruv-swarm subcommand flags. This lands on anchor 3 — concrete guidance present but incomplete and not reliably copy-paste ready. | 3 / 5 |
Workflow Clarity | The body is organized by feature category, not as a sequence: there is no ordered workflow connecting board-init → sync → verify, and no validation checkpoints anywhere despite covering batch and destructive operations (bulk ops, auto card movement, bidirectional sync, data recovery) — the rubric explicitly caps such skills at 3, and this is below even that cap since the "rough sequence" (anchor 2) exists only in isolated fragments like the issue-import snippet. It does not reach anchor 1 because sections are individually coherent, not incoherent. | 2 / 5 |
Progressive Disclosure | This is effectively a monolithic catalog: ~470 lines of command examples that clearly belong in split reference files, with no bundle files provided (no references/, scripts/, or assets/ directories exist). The only cross-references — "See also: [swarm-issue.md](.$swarm-issue.md), [multi-repo-swarm.md](.$multi-repo-swarm.md)" — use mangled paths (`.$` instead of `./`) and point to nonexistent files, so navigation is broken. Anchor 2 ("content that clearly belongs in separate files is inlined; or references are buried") fits; not 3 because the sole references present are dead links rather than merely unclear. | 2 / 5 |
Total | 9 / 20 Passed |