Content
72%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.
An exceptionally lean, high-signal body that assumes Claude's intelligence and gives concrete, verifiable commands and rules. Its main weaknesses are structural: the multi-step workflows and validation checkpoints are delegated to files missing from the bundle, and most referenced paths (workflows, schemas, templates) do not resolve.
Suggestions
Ship the referenced `workflows/`, `schemas/decision-format.md`, and `templates/` files in the bundle (or inline a minimal record/INDEX-row template) so the body's references resolve.
Wire `decisions check` explicitly into the update workflow as a validation checkpoint (e.g. "after any INDEX edit, run `decisions check`; fix duplicates before proceeding") to create a validate-fix-retry loop.
Add one short worked example of invoking the CLI (e.g. `decisions search --issue PROJ-189`, `decisions next-id`) inline instead of deferring everything to `--help`.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is ~40 dense lines covering warrant criteria, binding rules, lifecycle semantics, and an approval gate with zero padding and no explanation of concepts Claude already knows — e.g. "A record exists to stop a reversal: a reviewer or a future agent, reading the code alone, would undo the choice because the code cannot show its reason." Every line instructs; it fully assumes competence. | 5 / 5 |
Actionability | Concrete and verifiable: the CLI block (".agents/skills/decider/scripts/decisions <command> [options]"), named actions, env vars, and exact copy-paste approval phrasing ("Want me to create a decision entry?") all check out against the bundled script. It falls short of 5 because the invocation shown is a placeholder template — specific command examples (e.g. `decisions search --issue PROJ-189`) live only behind `--help`, and the format/creation specifics defer to files not shown. | 4 / 5 |
Workflow Clarity | Triggers, binding rules, and the approval gate are clearly stated, and the workflow table maps each trigger to a file, but the actual step sequences and validation checkpoints are delegated to `workflows/create-decision.md` and `workflows/update-decision.md`, which are not present in the bundle. The `check` action exists in the CLI but is never explicitly wired in as a validation checkpoint after INDEX edits, so checkpoints remain implicit — matching anchor 3 rather than 4. | 3 / 5 |
Progressive Disclosure | The body is well-sectioned with one-level-deep, clearly signaled references, and pushing CLI detail to `decisions --help` is good practice. But scoring against the actual bundle: of the six referenced paths, only the `scripts/decisions` script 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 navigation from the body breaks for five of them. | 3 / 5 |
Total | 15 / 20 Passed |