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.
A well-engineered operational workflow: concrete commands, explicit validation with feedback loops around a destructive move, and unambiguous sequencing. The only notable weakness is repetition between the steps and the Guardrails section, plus slightly dense inline boilerplate that could be factored out.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense procedural guidance with commands, routing rules, and failure paths, and it does not explain concepts Claude already knows. However, there is genuine repetition — the Guardrails section restates rules already stated in the steps (announce the change, run sync inline), and the context/operationGuidance handling contract in step 1 is expressed in several overlapping ways — which keeps it below the lean top anchor. | 4 / 5 |
Actionability | Fully executable commands are given throughout — `openspec instructions archive --change "<name>" --json`, `openspec status --change "<name>" --json`, `mkdir -p "<planningHome.changesDir>/archive"`, `mv "<changeRoot>" ...` — along with the exact JSON fields to parse and explicit routing for each prompt answer. The guidance is copy-paste ready and covers the common cases. | 5 / 5 |
Workflow Clarity | Six clearly sequenced steps with explicit validation checkpoints: artifact/task completion checks, a mandatory post-sync re-comparison of every capability, stop-on-failure rules ("If the sync failed, or any capability does not match, report what differs and stop — do not archive"), and a pre-move existence check for the destructive `mv`. Feedback loops and a guardrail checklist are both present, matching the top anchor. | 5 / 5 |
Progressive Disclosure | No bundle files exist, so all content lives in a single SKILL.md with well-organized step, guardrail, and output-template sections — good structure overall. Minor gaps: ~170 lines of dense procedural text (e.g., the shared store-selection paragraph and instruction-contract rules) is inlined where a reference file could carry it, and the `openspec-sync-specs` workflow is invoked without a path or link to its location. | 4 / 5 |
Total | 18 / 20 Passed |