Content
63%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 content is operationally rich - concrete CLI commands, JSON fields to inspect, branch handling for unconfigured projects and stores, and a clear capture table - and it appropriately frames exploration as a stance rather than a script. Its main weaknesses are verbosity from heavy repetition of the store-flag and confirmation rules, dense run-on paragraphs in the capture workflow, and a 345-line single-file structure with no progressive disclosure of the rarely-needed capture details. Restructuring and offloading would lift it substantially.
Suggestions
Move the detailed capture workflow (the numbered steps under 'When no change exists', ~60 lines used only when the user asks to capture) into a references/capture.md file and keep a short trigger condition plus link in SKILL.md, cutting main-file tokens and enabling one-level-deep progressive disclosure.
State the '--store <id>' stickiness rule once in the 'Store selection' section (e.g., 'every command below implicitly takes --store <id> when a store is selected') and delete the eight parenthetical repetitions throughout the body.
Consolidate the write-confirmation rule, currently restated four times (IMPORTANT paragraph, 'Keep a conversational record', 'Don't auto-capture', and the capture transition), into one authoritative statement and cross-reference it elsewhere.
Break the 10-line condition-laden paragraphs of capture steps 2-4 into short numbered sub-steps or a checklist so the validation sequence (status -> instructions -> create -> re-run status) is scannable rather than parsed from prose.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with genuine operational guidance and avoids explaining known concepts, but the '--store "<id>"' caveat is repeated parenthetically roughly eight times and the write-confirmation rule is restated in four places. Mostly efficient but could be tightened substantially by deduplicating; not 2 because the redundancy is repetition for emphasis rather than fluffy concept explanation. | 3 / 5 |
Actionability | Provides copy-paste-ready commands ('openspec list --json', 'openspec show "<spec-id>" --type spec --json --no-scenarios', 'openspec new change "<name>"'), specific JSON fields to read (root, changeRoot, existingOutputPaths), and a concrete capture-target table. Not 5 because capture steps 2-4 are enormous run-on paragraphs whose nested conditions make faithful execution error-prone. | 4 / 5 |
Workflow Clarity | The capture workflow has explicit validation checkpoints (re-run 'openspec status' after each artifact, verify the output path stays inside changeRoot, verify the output exists) and feedback loops for blocked or conditionally-skipped artifacts, and the no-root branching is enumerated. Not 5 because the sequence is buried in dense multi-clause prose rather than scannable steps, which hurts clarity even though checkpoints are present. | 4 / 5 |
Progressive Disclosure | The file is well-sectioned with clear headers, but it is a 345-line monolith with no bundle files at all. The detailed capture procedure (~60 lines of dense operational detail, including the repeated store-flag permutations) applies only in a specific sub-situation and is exactly the content that should be offloaded to a one-level-deep reference file. | 3 / 5 |
Total | 14 / 20 Passed |