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.
A highly actionable, well-sequenced workflow skill with copy-paste commands, explicit state handling, and useful output templates. Its weaknesses are repetition of the context/operationGuidance rules between Step 3 and Guardrails, one dense paragraph, and the absence of a verify-before-marking checkpoint.
Suggestions
State the context/operationGuidance handling rules once — either in Step 3 or as a short Guardrails bullet — instead of repeating them in both places.
Break the 150-word Store-selection paragraph into a short bulleted rule list (when to pass --store, which commands take it, stickiness) to cut reread cost.
Add a verify-before-marking checkpoint, e.g., confirm the change compiles or tests pass before flipping `- [ ]` to `- [x]`, and re-run `openspec status` on failure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and free of concept-explaining filler, but the context/operationGuidance contract is stated in full in Step 3 ("Treat `context` as a required prompt-level input... They are not evidence of task completion...") and then repeated nearly point-for-point in the Guardrails list ("Do not use context or operation guidance as proof that a task is complete", "Apply relevant project context; report conflicts...", "Consider every guidance entry...", "Do not copy runtime context..."). This duplicated block plus the single 150-word Store-selection paragraph could be meaningfully tightened, matching the 3 anchor. | 3 / 5 |
Actionability | Guidance is fully executable for an instruction-only skill: copy-paste-ready commands (`openspec status --change "<name>" --json`, `openspec instructions apply --change "<name>" --json`, `openspec list --json`), a concrete edit operation ("Mark task complete in the tasks file: `- [ ]` → `- [x]`"), explicit state handling for blocked/all_done, and complete output templates for in-progress, completion, and pause. Nothing is pseudocode and the common cases are covered, matching the 5 anchor. | 5 / 5 |
Workflow Clarity | The seven steps are clearly sequenced with state checks up front, explicit pause conditions for error recovery ("Pause on errors, blockers, or unclear requirements - don't guess"), and a post-session status report, plus a Guardrails checklist. It falls short of 5 because there is no validation checkpoint before marking a task complete — the loop goes straight from "Make the code changes required" to "Mark task complete" without verifying the change (e.g., build/test) succeeded. | 4 / 5 |
Progressive Disclosure | No bundle files exist and none are needed; the single body is well-sectioned (Steps, Output templates, Guardrails, Fluid Workflow Integration) with no nested or buried references, so it clears the monolithic and buried-reference anchors easily. It stays at 4 rather than 5 because the ~170-line body has minor organization gaps — the dense unbroken Store-selection paragraph and the repeated context/guidance rules read as inlined content that could be consolidated or trimmed. | 4 / 5 |
Total | 16 / 20 Passed |