Content
73%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 operational skill: the workflow is unambiguous, validated, and safe for a destructive batch operation, with concrete commands throughout. Its weaknesses are redundancy — repeated output templates and guardrails that restate step rules — and one underspecified hand-off to the sync-specs approach.
Suggestions
Collapse the step-9 example summary and the 'Output On Success/Partial Success' templates into one template section to remove near-verbatim duplication.
Trim Guardrails to only rules not already stated in the steps (e.g. keep the .openspec.yaml and date-format rules, drop the re-statements of prompting and chronological order).
Replace 'Use the openspec-sync-specs approach' with a one-line inline description of the merge mechanics or a concrete file reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The procedural steps are tight and command-driven, but there is real duplication: step 9's full example summary is repeated almost verbatim in the 'Output On Success' template, and several Guardrails ('Always prompt for selection, never auto-select', 'apply specs in chronological order') restate rules already given in the steps. This matches 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than the efficient anchor. | 3 / 5 |
Actionability | Nearly every step is executable: `openspec list --json`, `openspec status --change "<name>" --json`, checkbox-counting rules (`- [ ]` vs `- [x]`), the `### Requirement:` extraction pattern, and copy-paste bash for the archive move. The minor gap keeping it from a 5 is step 8a's 'Use the openspec-sync-specs approach (agent-driven intelligent merge)', which defers the most delicate operation to another skill's approach without inline mechanics. | 4 / 5 |
Workflow Clarity | Nine explicitly sequenced steps with real validation checkpoints for a batch/destructive operation: pre-flight status gathering (step 3), a consolidated status table with warnings (step 6), a single user confirmation before execution (step 7), per-change outcome tracking (success/failed/skipped), and explicit failure recovery ('If archive target exists, fail that change but continue with others'). This matches the anchor requiring explicit validation, error recovery, and checklist-style structure. | 5 / 5 |
Progressive Disclosure | The body is well-sectioned (Steps, Conflict Resolution Examples, Output templates, Guardrails) with no nested references and clear navigation, and no bundle files exist to consult. Minor gaps: the ~250-line body duplicates its output templates inline where a single template or a reference file would do, and 'the openspec-sync-specs approach' is an unsignaled external reference. This places it just below the well-split anchor at 5. | 4 / 5 |
Total | 16 / 20 Passed |