Content
81%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 highly actionable, well-sequenced workflow with executable CLI commands, explicit state and error handling, and useful output templates. Its main weakness is redundancy: the context/operationGuidance rules are stated twice (step 3 and Guardrails), and the full output templates inflate the body beyond a lean overview.
Suggestions
Deduplicate the context/operationGuidance rules: keep one canonical statement (either step 3 or the Guardrails) and reference it from the other location.
Collapse the three full output templates into one representative example with a note on the variations, cutting roughly 40 lines.
Tighten the store-selection paragraph by stating the sticky --store rule once instead of re-explaining the flag on each unscoped example.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly operational with no basic-concept padding, but the context/operationGuidance contract in step 3 ("Read and consider it... They are not evidence of task completion...") and the Guardrails section restate the same rules nearly verbatim ("Do not use context or operation guidance as proof that a task is complete", "Do not copy runtime context or operation guidance into implementation files"). Not 2 because there is no explanation of known concepts and most directives are lean; not 4 because the duplication exceeds minor trimming. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready commands with exact flags ("openspec status --change \"<name>\" --json", "openspec instructions apply --change \"<name>\" --json", "openspec list --json", "openspec store list --json"), exact edit syntax ("- [ ]\u2192 - [x]"), explicit state handling (blocked/all_done), and concrete output templates. Not 4 because the commands and examples cover the common paths (named change, inferred, ambiguous, blocked, all done); "Make the code changes required" is appropriately task-defined rather than vague. | 5 / 5 |
Workflow Clarity | A clear 7-step sequence with upfront state validation (parse status JSON, handle blocked/all_done before acting), explicit feedback loops for error recovery (pause on unclear task, design issues, errors; report and wait), loop-until-done semantics, a guardrail checklist, and end-of-session status reporting. Not 4 because checkpoints are present at entry, per-task, and exit; the workflow's state checks and pause conditions serve as the validation for its batch task loop. | 5 / 5 |
Progressive Disclosure | Well-organized single-file body with clear headers (Store selection, Input, Steps, Output During/On Completion/On Pause, Guardrails, Fluid Workflow Integration) and no buried or nested references; no bundle files exist, and nothing strictly requires one. Not 5 because at ~170 lines with three full output templates plus a store-selection mechanics paragraph, it exceeds a lean overview and parts (output templates, store rules) could be consolidated or split out. | 4 / 5 |
Total | 17 / 20 Passed |