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 well-gated, clearly sequenced upgrade workflow with strong progressive disclosure and explicit validation checkpoints, security controls, and an untrusted-evidence stance. The main gap is actionability: many steps are stated as abstract imperatives rather than executable or example-backed guidance, which forces the reader to reinvent mechanics the skill could have shown. A minor conciseness defect (a duplicated policy sentence) and an unresolvable shared-reference link keep it just below the top band.
Suggestions
Ground the abstract steps with one concrete worked example each — e.g. a sample command pair for resolving a source identity, or a filled-in one-line concern record (upstream old/new contract, consumer, failure mode, migration) so the format is unambiguous.
Deduplicate "Preserve historical executable fixtures only when they still support a current test" (appears in both the records section and Resolve concerns) and move the long point-in-time-records paragraph into a reference file.
Fix or inline the "../_shared/implementation-discovery.md" dependency so the Discover-current-contracts step is self-contained within the skill bundle.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, assumes Claude's competence, and contains no tutorial padding or explanations of known concepts — every section is project-specific policy. It falls short of anchor 5 only through minor redundancy: "Preserve historical executable fixtures only when they still support a current test" appears verbatim in two sections, and the point-in-time records paragraph is a long inline policy block that could be tightened. | 4 / 5 |
Actionability | The workflow is concrete at the procedure level — numbered audit steps, references to real checked-in tools ("[release ledger collector](scripts/collect-release-ledger.py)", "Inspect the collector's current help and source before use"), and explicit security controls ("mode 0600", "byte and record ceilings"). But most steps are abstract directives with no executable form ("Resolve immutable source identities and publication status", "Compare resolved dependency graphs and distributed artifacts") — anchor 3: some concrete guidance but missing the specific steps to execute, short of anchor 4's mostly-executable guidance. | 3 / 5 |
Workflow Clarity | The sequence is explicit and gated: plan outcomes → discover contracts → audit upstream ranges → resolve concerns → verify, with concrete checkpoints ("An unresolved high-impact concern blocks the upgrade", "Implement migrations in upstream release order", a "Before handoff" checklist, and the rule that expected version output does not establish contract execution). This matches anchor 5 — clear sequence, explicit validation steps, and a checklist for a complex process. | 5 / 5 |
Progressive Disclosure | Good split: the ~105-line body stays at overview level while detail lives in one-level-deep, clearly linked references (release-ledger.md, contract-audit.md, hermes.md) and checked-in scripts, with exemplary conditional loading ("load the conditional Hermes upgrade variant... only when the dependency target is Hermes" — hermes.md itself is marked "Load this reference only when..."). It misses anchor 5 because the core workflow reference "[Discover the Current Implementation](../_shared/implementation-discovery.md)" points outside the skill bundle and does not resolve in this checkout, leaving the entry-point step unverifiable. | 4 / 5 |
Total | 16 / 20 Passed |