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.
The content is a well-sequenced, largely executable workflow with real validation checkpoints (status checks, task counting, existence checks, user confirmations) and concrete commands throughout. The main gaps are minor: a small amount of redundancy between the guardrails and the steps, a couple of slightly vague spots ('typically tasks.md', the delta-spec comparison method), and no post-archive verification.
Suggestions
Add a post-archive verification step (e.g., confirm the archived path exists and the source path is gone) and a retry path for the target-already-exists error to complete the validation loop.
Replace 'typically tasks.md' with the definitive task-file location or an explicit lookup rule, and either specify how to diff delta specs against main specs or point to a concrete reference for the comparison.
Trim redundancy by cutting Guardrails entries that restate steps verbatim and removing the opening line that duplicates the frontmatter description.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and procedural with concrete commands and no concept explanations, but has minor trims available: the opening line repeats the frontmatter description and the Guardrails section restates four points already made in the steps (e.g., 'Always prompt for change selection if not provided' vs. step 1's 'IMPORTANT'). | 4 / 5 |
Actionability | Mostly executable guidance with exact commands ('openspec list --json', 'openspec status --change "<name>" --json', 'mkdir -p openspec/changes/archive', 'mv ... archive/YYYY-MM-DD-<name>'), explicit task-marking rules, and defined prompt options. Minor gaps: 'typically tasks.md' leaves the tasks-file location vague and the delta-spec comparison gives no concrete method. | 4 / 5 |
Workflow Clarity | A clear six-step sequence with explicit validation checkpoints — artifact status via openspec status, task completion counting, target-existence check with a fail-and-suggest path, and AskUserQuestion confirmations. It falls short of anchor 5 because there is no post-archive verification step or retry loop after the target-exists error, and the comparison in step 4 lacks a feedback loop. | 4 / 5 |
Progressive Disclosure | No bundle files exist, and the single workflow is well sectioned (Input, Steps, Output On Success, Guardrails) with appropriate one-level delegation to the openspec-sync-specs skill. At ~100 lines it exceeds the under-50-line exception, and there is no top-level overview section, so anchor 4 fits rather than 5. | 4 / 5 |
Total | 16 / 20 Passed |