Content
77%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 a highly actionable, well-validated workflow with executable commands and thorough error handling, but it is held back by redundant restatements of the same guardrails and a monolithic single-file structure with bold pseudo-headers instead of real sections or one-level-deep references. Tightening the duplication and splitting the dense policy paragraphs would raise both weak dimensions.
Suggestions
State the planning boundary once (e.g., in the opening paragraph) and have the Guardrails section reference it instead of restating it; the same applies to the root-null/project-check rules duplicated between the Project check section and step 2.
Convert bold pseudo-headers to real markdown headings (## Store selection, ## Project check, ## Steps) and move the dense store-selection and store-declaration edge-case policy into a references/ file linked from a short inline summary.
Merge the duplicated 're-read dependency artifacts from disk' and 'context/rules are constraints, not content' guidance into single statements in the Artifact Creation Guidelines section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly all content is OpenSpec-specific procedural knowledge Claude would not already know, but there is noticeable redundancy: the planning boundary is stated twice nearly verbatim (opening paragraph and Guardrails), root-null/project-check handling is duplicated between the Project check section and step 2, and 're-read dependencies from disk' and 'do not copy context/rules into the file' each appear twice. This is more than the minor trimmable instances of anchor 4. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready commands cover the common cases ('openspec context --json', 'openspec new change "<name>"', 'openspec status --change "<name>" --json', 'openspec instructions <artifact-id> --change "<name>" --json'), including store-scoped and explicit-schema variants, plus explicit JSON fields to parse from each command's output. | 5 / 5 |
Workflow Clarity | A clear 7-step sequence for a batch multi-file operation with explicit validation checkpoints: a project check before any write, re-running status after each artifact, verifying each artifact file exists before proceeding, and explicit error-recovery branches (root null, unresolvable store declaration, glob paths escaping changeRoot), plus a todo-list checklist. This matches the top anchor including feedback loops. | 5 / 5 |
Progressive Disclosure | The numbered steps provide a sequence, but there are no bundle files and no real markdown headers (only bold pseudo-headers), and the dense store-selection and project-check policy paragraphs are inlined walls of parenthetical text that belong in a referenced file or properly headed sections. This fits 'some structure but could be better organized' better than anchor 4's 'minor organization gaps'. | 3 / 5 |
Total | 16 / 20 Passed |