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.
An exceptionally actionable and well-sequenced release runbook with real validation checkpoints and failure recovery, plus one well-integrated reference file. The main improvements are tightening the repeated merge-queue guidance and moving some inlined sub-workflow detail into reference files.
Suggestions
Consolidate the merge-queue guidance (currently restated in Principles, the changeset-PR continuation, and the Version Packages validation sections) into one place and cross-reference it to save tokens.
Move the detailed Version Packages PR validation steps and the beta-cutting path into a reference file (like release-notes.md) so SKILL.md stays a leaner overview of the state machine.
Trim the artifact-verification bullet about the 8 openspec-* archives and SHA256SUMS to the essential rule (wait for SHA256SUMS via the Binaries workflow) and keep exact counts in a reference if needed.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, imperative, and free of explanations of concepts Claude already knows — it teaches only non-obvious, repo-specific constraints (tag conflicts, merge-queue semantics, Binaries workflow timing). It falls short of a 5 because merge-queue caution is repeated across Principles, the changeset-PR continuation, and the Version Packages validation sections, and a few passages could be tightened further. | 4 / 5 |
Actionability | Guidance is copy-paste ready throughout: exact commands with flags and jq filters ("gh release list ... --exclude-drafts --exclude-pre-releases ... --jq 'max_by(.publishedAt) | {tagName, publishedAt}'", "git log --first-parent ... <stable-tag>..origin/main", "pnpm exec changeset status"), plus concrete verification commands like "npm view @fission-ai/openspec@<version> version". Specific examples cover the common cases. | 5 / 5 |
Workflow Clarity | The workflow is a clearly sequenced state machine with a nine-state audit classification and explicit validation checkpoints: validate with "pnpm exec changeset status" before pushing, require "baseRefOid" to equal current origin/main, base-to-head worktree comparison, independent verification of all three release artifacts, and a dedicated failure-handling section with recovery guidance and feedback loops. | 5 / 5 |
Progressive Disclosure | The single bundle reference (references/release-notes.md) is real, one level deep, clearly signaled via a markdown link, and context-gated ("Once all artifacts exist, read [references/release-notes.md]..."), and the body is organized under clear section headers. It misses a 5 because the ~170-line body inlines detailed sub-workflows (Version Packages validation, beta path, failure handling) that could be split into references to keep SKILL.md closer to an overview. | 4 / 5 |
Total | 18 / 20 Passed |