Content
65%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 exceptionally lean and its CLI claims fully verify against the shipped script, but the bundle ships none of the five referenced workflow/schema/template files, leaving the create/update path unexecutable, and the `check` validation action is never woven into a workflow for the skill's destructive INDEX/record edits.
Suggestions
Ship the referenced bundle files — workflows/create-decision.md, workflows/update-decision.md, schemas/decision-format.md, templates/decision-entry.md, templates/index-row.md — or inline their essential steps; all five resolve to no file in the bundle, so the primary create/update procedure is unreachable.
Weave `decisions check` into the create/update path as an explicit validation checkpoint (e.g., 'after any INDEX edit, run decisions check and fix error= findings before proceeding'); the action exists in the CLI but the body never says when to run it, and the skill includes destructive record removal.
Add a short numbered creation sequence in the body (next-id → draft from the template → add the INDEX row → decisions check) so the core workflow is executable even without the workflow files.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 44-line body has zero padding: no tutorial-level explanation of what an ADR is, no library talk, and every sentence states a rule, criterion, or pointer ("A record exists to stop a reversal", the warranted/not-warranted lists, the approval phrasing). Not 4: there is no over-explanation left to trim, matching the 'every token earns its place' anchor. | 5 / 5 |
Actionability | The CLI block's claims all verify against the shipped script (actions `search`, `search --issue`, `list`, `next-id`, `get`, `check`; `DECISIONS_DIR`/`DECISIONS_BASE_REF`/`DECISION_ID_*`; "There is no bare `issue` action" confirmed) and the approval phrasing is copy-paste ready. But the core create/update procedures are delegated to files absent from the bundle ("Follow `workflows/update-decision.md`", "Format: `schemas/decision-format.md`", "`templates/decision-entry.md`"). Anchor 3 fits: concrete guidance exists but the primary action's procedure is unreachable — more than a minor gap. | 3 / 5 |
Workflow Clarity | The trigger→workflow table and the explicit approval checkpoint ("Never create a decision document without explicit user approval") structure the flow, but the actual step sequences live in the missing workflow files and the CLI's `check` action is never placed in a workflow. Because the skill involves destructive operations (removing a routine record's document, INDEX edits), the missing validation steps cap this at 3 per the destructive/batch guideline. | 3 / 5 |
Progressive Disclosure | The body is a well-sectioned, one-level-deep hub (workflows table, format pointers, `decisions --help` delegation), but scored against the actual bundle only `scripts/decisions` exists: `workflows/create-decision.md`, `workflows/update-decision.md`, `schemas/decision-format.md`, `templates/decision-entry.md`, and `templates/index-row.md` are all absent, so most navigation targets dangle. Better organized than anchor 2, but five broken reference paths are not anchor 4's 'minor organization gaps'. | 3 / 5 |
Total | 14 / 20 Passed |