Content
77%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.
An exceptionally rigorous operational workflow: fully executable commands, exact JSON contracts, and validation checkpoints at every destructive boundary of the batch archive. The weaknesses are redundancy (duplicated output templates and a guardrails section that restates the steps) and a monolithic 377-line body with no progressive disclosure of examples or templates into reference files.
Suggestions
Move the conflict-resolution examples and the 'Output On Success/Partial/No Changes' templates into a references/ file (e.g., references/examples.md) and keep a single canonical output format in the body, cutting the duplicated step-9 examples.
Trim the guardrails section to only rules not already stated in steps 3d/8c (e.g., the target-name computation and archive-collision rules appear three times) to reduce token cost without losing constraints.
Tighten the store-selection paragraph by replacing the repeated per-command flag instructions with one short rule ('append --store <id> to every command that reads or writes specs/changes') plus the command list.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and purely operational with no explanations of concepts Claude already knows, but there is noticeable redundancy: output templates are duplicated (step 9 examples vs. the 'Output On Success/Partial Success' sections), roughly 28 guardrail bullets restate earlier steps verbatim (e.g., the target-name rule appears in steps 3d, 8c, and the guardrails), and the store-selection paragraph is convoluted. This fits anchor 3 (mostly efficient but could be tightened) better than 2, since the padding is repetition rather than unnecessary explanation. | 3 / 5 |
Actionability | Fully executable throughout: exact commands (`openspec list --json`, `openspec status --change "<name>" --json`, `mkdir -p`/`mv`), exact JSON fields to parse (`schemaName`, `planningHome`, `artifactPaths`), the literal match pattern `### Requirement: <name>`, concrete table and output templates, and worked conflict-resolution examples. This matches anchor 5 (copy-paste ready commands covering common cases), one level above anchor 4's 'minor gaps'. | 5 / 5 |
Workflow Clarity | Nine clearly sequenced steps with explicit validation checkpoints and feedback loops for this batch/destructive operation: archive-target collision check before any spec write (3d), specs-rule snapshots fetched before the first write (7), main-spec verification before moving `changeRoot` (8b), a re-check immediately before the move plus a post-move nest check (8c), and atomic stop conditions with per-change outcome tracking. The batch-operation cap does not apply and this matches anchor 5, including the guardrails checklist; anchor 4 would require missing checkpoints, which is not the case. | 5 / 5 |
Progressive Disclosure | No bundle files exist, so the 377-line body is monolithic. Internal structure is good (numbered steps, headers, examples), but content that would naturally live in separate reference files — conflict-resolution examples and output templates — is inlined, and there is no overview-to-detail split. This fits anchor 3 (some structure, content that should be separate is inline) rather than 2, since the file is well organized and navigable. | 3 / 5 |
Total | 16 / 20 Passed |