Content
81%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, well-sequenced workflow skill with real validation feedback loops and a sensible reference bundle. Its weakness is token efficiency: heavy rhetorical justification and repeated restatement of the same rules inflate the body well beyond what the instructions require.
Suggestions
State each invariant once: the write-the-skeleton-first rule currently appears in the opening section, again in Step 8, and again in the grep verification — keep the instruction and the check, and cut the two intervening re-explanations.
Trim the motivational prose around rules (e.g. "a filed-and-open `high` is a live unpatched defect ... an attack map with a timer on it", the 66-line and +85/-40 anecdotes) to one-line justifications; the rules themselves are strong enough to be followed without the persuasion.
Cite `references/registering-a-stack.md` and `references/wikilink-check.md` directly from the relevant steps (Step 9 and Step 7) instead of routing readers through `workflow-steps.md`, and consider moving the comment-delta history/traps into a reference file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body carries genuinely non-obvious project knowledge (the uncommitted-diff trap, the moved-base comment-delta trap, the stash-sharing hazard) and never explains concepts Claude already knows, so it is well above the verbose-padded anchors. But it is noticeably padded in style: rules are stated then restated (the skeleton-first rule appears three times — at the top, in Step 8, and in the grep check), and persuasive asides like "the issue is an attack map with a timer on it" and the 66-line comment-delta anecdote could be tightened without losing the instruction. That places it at the 3 anchor ('mostly efficient but could be tightened') rather than 4, where only minor trimming would be needed. | 3 / 5 |
Actionability | Nearly every step has copy-paste-ready commands: the environment probe block, `BASE=$(git config ...)`, `git status --porcelain` grouping, `bun run scripts/comment-delta.ts "$BASE"`, `gh pr create --base "$BASE" --title ... --body-file`, and the verbatim PR-body heredoc. Concrete examples cover the common cases (stacked vs. unstacked, changeset present vs. absent, network vs. none), matching the 5 anchor; the few placeholders (`bun test <scope>`, `# minus config.json, README.md`) are deliberate templates, not gaps. | 5 / 5 |
Workflow Clarity | Steps 0–10 are explicitly ordered with "Run the steps in order", and validation checkpoints are everywhere: the environment probe runs before Step 0, `validate-changesets.sh` gates Step 2, the changeset check is re-run after the committing step, steps 3 and 4 are re-run after user fixes, and the closing `grep -c` checks (both must print 5) validate the deliverable. Blocked gates get defined static equivalents instead of silent skips, which is exactly the error-recovery feedback loop the 5 anchor describes. | 5 / 5 |
Progressive Disclosure | Detail is appropriately split into five real, one-level-deep reference files (`workflow-steps.md`, `issue-filing-example.md`, `auditing-defect-classes.md`, `wikilink-check.md`, `registering-a-stack.md`), and the three the body cites directly are clearly signaled ("A full worked `gh issue create` ... is in `references/issue-filing-example.md`"). It falls short of 5 because `wikilink-check.md` and `registering-a-stack.md` are only reachable through a second hop via `workflow-steps.md` rather than from the main file, and some content (the comment-delta rationale and its case studies) is inlined where the established pattern would put it in a reference. | 4 / 5 |
Total | 17 / 20 Passed |