Content
67%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 successfully teaches a non-procedural stance with concrete commands, artifact paths, and a capture mapping, all clearly sectioned. Its main cost is redundancy — the stance principles are repeated across three sections and the illustrative dialogues inflate length without adding operational detail.
Suggestions
Merge 'What You Don't Have To Do' and 'Guardrails' into a single section — they currently repeat the same principles ('don't implement', 'don't rush', 'don't force structure', 'do visualize') already stated in the opening stance paragraph.
Trim or externalize the four full example dialogues (~100 lines) to one or two compact illustrations; the remaining length reduction would materially improve token efficiency, the lowest-scoring dimension.
Specify what to do with the `openspec list --json` output when multiple changes exist (e.g., which artifact to read first), closing the minor actionability gap.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body restates the same core principles in three places — "This is a stance, not a workflow" (line 16), the "What You Don't Have To Do" list (lines 136-143), and the "Guardrails" section (lines 281-290) repeat 'don't implement', 'don't rush', 'don't force structure', and 'do visualize'. There is no conceptual over-explanation, but the ~100 lines of example dialogues plus the redundant sections could be tightened, matching anchor 3 better than the padding level of anchor 2. | 3 / 5 |
Actionability | The body provides concrete, executable anchors: the `openspec list --json` command, exact artifact paths (`openspec/changes/<name>/proposal.md`, `design.md`, `tasks.md`), an insight-type-to-artifact capture table, and transition commands (`/opsx:new`, `/opsx:ff`). Minor gaps remain (e.g., what to do with the `openspec list` output beyond the three bullets), matching anchor 4. | 4 / 5 |
Workflow Clarity | Although deliberately non-procedural, the operating sequence is unambiguous: check context at start, branch on whether a change exists, read artifacts for context, offer to capture (never auto-capture), and the user decides. Entry-point examples and ending guidance cover the paths. No destructive or batch operations exist, so no validation cap applies, but there are no explicit checkpoints of the anchor-5 level either. | 4 / 5 |
Progressive Disclosure | A single well-organized file with clear section headers and no bundle files to navigate. The long example dialogues (lines 149-247) could plausibly live in a reference file, which keeps this at anchor 4 ('minor organization gaps') rather than a fully split structure. | 4 / 5 |
Total | 15 / 20 Passed |