Content
75%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.
A strong, actionable workflow: numbered steps, executable commands, explicit validation checkpoints, and user-confirmation gates before an irreversible move. The main gaps are the absence of a post-archive verification step, a somewhat vague step 4 (delta spec comparison), and minor redundancy between the Guardrails section and the numbered steps.
Suggestions
Add a post-archive verification step, e.g. re-run `openspec list --json` and confirm the archived change no longer appears, so the destructive `mv` is validated rather than fire-and-forget.
Make step 4 concrete: specify how to compare a delta spec with `openspec/specs/<capability>/spec.md` (which sections to read, how to classify adds/modifications/removals) instead of the directional "Determine what changes would be applied".
Trim the Guardrails entries that restate numbered steps (change-selection prompting, sync assessment) and the redundant opening sentence, keeping only the non-duplicative ones (preserve .openspec.yaml, don't block on warnings).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient — concrete commands and JSON fields with no explanations of concepts Claude already knows. Minor trimmable redundancy exists: the opening line repeats the frontmatter description verbatim, and several Guardrails entries ("Always prompt for change selection", "If delta specs exist, always run the sync assessment") restate earlier steps. | 4 / 5 |
Actionability | Mostly executable guidance with copy-ready commands (`openspec list --json`, `openspec status --change "<name>" --json`, `mkdir -p`, `mv`) and named JSON fields to parse. Minor gaps: step 4's delta-spec comparison is directional ("Determine what changes would be applied") rather than a concrete procedure, and the tasks file location is vague ("typically `tasks.md`"). | 4 / 5 |
Workflow Clarity | A clearly sequenced 6-step workflow with strong validation checkpoints — artifact status check, task completion check, AskUserQuestion confirmation gates, and a target-collision check with explicit error handling. It falls short of level 5 only because there is no post-archive verification that the move succeeded (e.g., re-running `openspec list` to confirm the change is no longer active). | 4 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are all absent) and the body references no external paths, so nothing is dangling. The single-file body is well organized with clear headers and appropriately self-contained at ~105 lines, though it sits above the under-50-line exception where organization alone would merit a 5. | 4 / 5 |
Total | 16 / 20 Passed |