Content
88%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.
This is a strong instructional skill: an explicitly sequenced 11-phase workflow with validation checkpoints, error-recovery branches, graceful exits, and fully executable OpenSpec CLI commands with JSON output handling. The only notable improvements are deduplicating the command reference table and moving the artifact format templates out of the main file to trim length.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense operational guidance — exact CLI invocations, JSON fields to read, and branching rules for store selection and root detection — with little explanation of concepts Claude already knows. The main trims available are the 8-row command reference table duplicated nearly verbatim in Phase 11 and the 'Quick Reference' exit section, and the ASCII-diagram placeholder block. Fits anchor 4 ('Efficient; minor instances of over-explanation that could be trimmed') better than 3, since the padding is localized duplication rather than a pattern of unnecessary explanation. | 4 / 5 |
Actionability | Commands are copy-paste ready with correct JSON-reading instructions ('openspec instructions proposal --change "<name>" --json' then write to 'resolvedOutputPath', 'openspec archive "<name>" --yes' with the reason for --yes given), and each phase has verbatim display templates. Fully executable guidance covering the common cases — the anchor 5 example; it exceeds anchor 4 because even edge handling (root null, store errors, CLI missing) is concrete. | 5 / 5 |
Workflow Clarity | Eleven clearly sequenced phases with explicit PAUSE checkpoints, a preflight CLI check, a project-setup validation step (read 'root' from 'openspec list --json', with the non-zero exit explained), and error-recovery branches for both root-null paths and mid-session exits. This matches anchor 5 ('Clear sequence with explicit validation steps; feedback loops for error recovery'), exceeding anchor 4's 'minor validation gaps' — validation is present at every risky transition. | 5 / 5 |
Progressive Disclosure | The file is well-sectioned (Preflight, Phases 1-11, Graceful Exit, Guardrails) and self-contained with no bundle files, so there are no buried or nested references. However, at ~560 lines, material that could live in separate reference files — the artifact format templates and the command reference tables — is inlined. Fits anchor 4 ('Good structure; most content is appropriately placed... minor organization gaps') rather than 5, which expects content appropriately split across files, and clearly above 3, where structure is weak or references unclear. | 4 / 5 |
Total | 18 / 20 Passed |