Content
73%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 well-sequenced, highly actionable guided workflow with strong validation and error-recovery branches, and the EXPLAIN/DO/SHOW/PAUSE structure makes the teaching flow unambiguous. Its main weakness is redundancy: the skill-reference table and several guardrail rules are repeated, inflating token cost without adding information. Organization within the single file is good, though nothing is split out to references.
Suggestions
Deduplicate the two near-identical skill-reference tables by defining the table once and referencing it from both the recap and the 'user just wants skill reference' exit path.
Trim the Guardrails section of rules already enforced inline per-phase (e.g., 'Keep narration light' and pause guidance), keeping only the cross-cutting rules.
Provide concrete commands for the codebase-analysis step (e.g., grep patterns for TODO/FIXME and ': any') so every phase is executable as written.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The bulk of the length is functional display-template content, but the skill-reference table appears twice nearly verbatim (Phase 11 recap and 'User just wants skill reference'), and the Guardrails section restates per-phase rules already stated inline ('Keep narration light', pause guidance). Matches 'mostly efficient but could be tightened'; not 4 because the duplication is systemic rather than minor. | 3 / 5 |
Actionability | Provides concrete executable commands throughout ('openspec --version', 'openspec list --json', 'openspec new change "<name>"', 'openspec instructions proposal --change "<name>" --json', 'openspec archive "<name>" --yes') plus exact display templates and resolvedOutputPath write instructions. Minor gaps keep it below 5: the codebase scanning heuristics (TODO/any-typing hunts) get no concrete commands, and 'openspec status' is cited for changeRoot without showing the initial invocation. | 4 / 5 |
Workflow Clarity | Clear 11-phase sequence with explicit PAUSE checkpoints, preflight CLI validation, a JSON-based project root check, and genuine error-recovery branches (CLI not installed, 'root': null with separate auto-selected vs. explicit-request handling, and the 'Declared in'/'Invalid store declaration' config-error path with 'show message and fix'). Matches the anchor for explicit validation steps with feedback loops for error recovery. | 5 / 5 |
Progressive Disclosure | No bundle files exist; the single file is well-structured with numbered phases and a consistent EXPLAIN/DO/SHOW/PAUSE pattern, and the inline templates are runtime-needed content rather than misplaced reference material. Minor organization gaps (duplicated skill tables, no split of long display scripts) match anchor 4; not 5, which requires well-signaled one-level-deep references that are absent here. | 4 / 5 |
Total | 16 / 20 Passed |