Content
70%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 rigorous, highly actionable workflow with excellent sequencing, validation checkpoints, and failure recovery for a destructive archive operation. Its weaknesses are token efficiency — repeated contracts and a Guardrails section that restates the steps — and a monolithic single-file layout with an unlinked dependency on the openspec-sync-specs skill.
Suggestions
Trim the instructions-archive context/operationGuidance block and the Guardrails section to rules not already stated in the steps; lines like "Never archive while a spec sync is still in flight" and "If delta specs exist, always run the sync assessment" duplicate step 4 verbatim.
Replace step 4's nested conditional prose (ADDED/MODIFIED/REMOVED/RENAMEED combinations) with a compact delta-composition-to-outcome table to cut tokens and speed parsing.
Move the shared store-selection/project-check preamble into a referenced file (e.g. references/store-selection.md) and give the `openspec-sync-specs` workflow a concrete path or link so the inline-sync call is actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is information-dense with no conceptual padding (it never explains what OpenSpec is), but the instructions-archive context/operationGuidance block restates the same contract several ways ("Keep both fields separate from built-in steps...", "Do not infer replacement paths...", "These are prompt-level behavior contracts, not enforceable checks"), the Guardrails section repeats rules already stated in steps 3-5, and step 4's nested conditional prose could be a compact table. It could be noticeably tightened without losing anything. | 3 / 5 |
Actionability | Nearly every step has copy-paste commands with exact JSON fields to read ("openspec status --change \"<name>\" --json", "mkdir -p \"<planningHome.changesDir>/archive\"", "mv \"<changeRoot>\"...") plus exact prompt options and an output template. The gap: step 4 says "run the `openspec-sync-specs` workflow inline" with no concrete invocation or reference, and the post-sync verification ("re-run the comparison from the top of this step") prescribes checks without a method for performing them. | 4 / 5 |
Workflow Clarity | Six clearly sequenced numbered steps with explicit validation checkpoints and feedback loops throughout: strict JSON parsing rules ("Require exactly one match and nonnegative integer totalTasks"), confirm-before-proceed warnings, sync-blocked logic, post-sync re-verification ("re-run the comparison from the top of this step... each capability must now read as already synced"), and stop-on-failure handling ("report what differs and stop — do not archive"), plus a Guardrails checklist. This matches the top anchor for a destructive move workflow. | 5 / 5 |
Progressive Disclosure | The single ~220-line file is well-sectioned but everything lives inline: the generic store-selection and project-check preamble reads like shared boilerplate, and step 4's canonical sync contract is reference-shaped content that could sit in a separate file. The one external dependency it names ("run the `openspec-sync-specs` workflow inline") is not signaled with a path or link, so navigation to it is implicit. | 3 / 5 |
Total | 15 / 20 Passed |