Content
75%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 lean and action-oriented, anchored by concrete openspec CLI commands, explicit JSON field parsing, and a clear status-driven decision tree with verification. The main gaps are an abstract artifact-write step and the absence of a validate→fix→retry feedback loop, which together keep it just short of the top anchors.
Suggestions
Replace the abstract 'Write to the output path specified' with a concrete write mechanism or short example so the artifact-creation step is copy-paste ready.
Add an explicit validate→fix→retry feedback loop after writing an artifact (e.g., re-run openspec status and remediate if the artifact is not recognized as done) to lift workflow clarity toward 5.
Consider moving the spec-driven artifact patterns into a short references file and signaling it from the body, which would separate schema-specific detail from the core workflow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body uses concrete CLI commands and parses specific JSON fields without explaining concepts Claude already knows, though the 'Artifact Creation Guidelines' section and the repeated context/rules guardrail (stated in step 3 and again in Guardrails) are minor trimmable redundancy. | 4 / 5 |
Actionability | Provides concrete, executable bash commands and specific JSON field-by-field parsing guidance with clear decision branches, but the actual artifact-writing step ('Write to the output path specified') is described abstractly rather than with a concrete write command or example. | 4 / 5 |
Workflow Clarity | A clear numbered sequence with three explicit status branches and a verification checkpoint ('Verify the artifact file exists after writing') plus STOP markers, though it lacks a full validate→fix→retry error-recovery feedback loop and the blocked branch offers no retry path. | 4 / 5 |
Progressive Disclosure | Well-organized with clear section headers (Input, Steps, Output, Artifact Creation Guidelines, Guardrails) in a self-contained file with no nested references; the inlined spec-driven pattern block is a minor organization gap that in a larger system could warrant its own schema reference. | 4 / 5 |
Total | 16 / 20 Passed |