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.
The body is a highly actionable, well-sequenced workflow with genuine validation checkpoints and error-recovery branches, all backed by copy-paste-ready commands. Its main weakness is the dense, clause-heavy prose in the store-selection and project-check sections and redundant --schema guidance, which cost token efficiency without adding clarity.
Suggestions
Rewrite the store-selection paragraph as a short bullet list (discover ids, which commands take --store, stickiness rule) — the current nested-clause prose is the single densest block in the file.
State the --schema rule once (in step 2 or step 3) and drop its repetition in the other step and in Guardrails.
Consider splitting the project-check error-triage cases (root null vs. "Declared in" store-resolution errors) into a compact two-row decision list so the branch conditions are scannable at a glance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient — the content is non-obvious CLI semantics Claude cannot infer — but the store-selection paragraph is a dense block of nested clauses that could be tightened into bullets, and the --schema guidance is repeated three times (step 2, step 3, and Guardrails). Fits anchor 3 (could be tightened) rather than 2, since there is no padding about concepts Claude already knows. | 3 / 5 |
Actionability | Every step ships a copy-paste-ready command (openspec list --json, openspec new change "<name>", openspec status --change "<name>" --json, openspec instructions <first-artifact-id> --change "<name>") with the exact JSON fields to read (root, planningHome, changeRoot, artifactPaths, nextSteps) and an exact ask-the-user prompt. Fully executable with placeholders covering the common cases. | 5 / 5 |
Workflow Clarity | Clear numbered sequence with an explicit pre-write validation checkpoint (run openspec list --json and read root before any write), detailed error-recovery branches (root null vs. the "Declared in"/"Invalid store declaration" case, auto-selected vs. explicit-request handling), and a hard STOP step with guardrails. Matches the anchor-5 pattern of explicit validation with feedback loops. | 5 / 5 |
Progressive Disclosure | No bundle files exist and the ~75-line body is organized into clearly labeled sections (Store selection, Project check, Input, Steps, Output, Guardrails) with no nested references. Falls short of 5 only because the two long prose sections (store selection and project check) are dense reference-style material that could be restructured into bullets or split into separate sections. | 4 / 5 |
Total | 17 / 20 Passed |