Content
68%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-structured, actionable instruction body with concrete paths, commands, and an output template. Its main deficiencies are the missing post-apply validation/feedback loop in a destructive batch operation (capping workflow clarity at 3) and minor redundancy between the merging principle section and step 3.
Suggestions
Add an explicit validation checkpoint after applying changes — e.g., re-read each modified main spec and confirm expected requirements/scenarios are present and removed ones are gone — before showing the summary, to satisfy the destructive/batch feedback-loop requirement.
Fold the 'Key Principle: Intelligent Merging' bullets into step 3c and drop the opening line that duplicates the description, removing the redundant passages.
Consider moving the delta spec format reference to a references/ file (or converting bold pseudo-headers to proper markdown headings) to tighten the main body's organization.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly lean procedural instruction with concrete paths and commands, but there are minor trimmable instances: the opening sentence repeats the frontmatter description, and the 'Key Principle: Intelligent Merging' section restates guidance already given in step 3c. This matches the 'efficient; minor instances of over-explanation' anchor rather than the fully lean level-5 anchor. | 4 / 5 |
Actionability | Guidance is mostly executable — exact file paths (`openspec/changes/<name>/specs/*/spec.md`), a runnable command (`openspec list --json`), per-delta-type apply rules, and a copy-paste output template. It falls short of fully executable because 'Apply changes intelligently' and 'use your judgment to merge changes sensibly' leave key merge decisions unspecified. | 4 / 5 |
Workflow Clarity | The numbered sequence is clear with some checkpoints ('If no delta specs found, inform user and stop', 'If something is unclear, ask'), but there is no validation step verifying the result after applying changes. Because the operation is batch and destructive (REMOVED requirements across multiple capability specs), the rubric caps workflow clarity at 3 despite the otherwise clean sequence. | 3 / 5 |
Progressive Disclosure | The skill is self-contained with no bundle files, organized into Steps, Delta Spec Format Reference, Key Principle, Output, and Guardrails sections. Structure is good with minor gaps — headers are bold text rather than markdown headings, and the ~25-line inline format reference could arguably live in a references file — matching the 'good structure; minor organization gaps' anchor. | 4 / 5 |
Total | 15 / 20 Passed |