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.
The body is a well-sequenced, highly actionable migration procedure with explicit validation gates, a definition of done, and a genuine interactive feedback loop for fragment resolution. Its main weaknesses are repetition — core policies are restated four to five times across sections — and a monolithic single-file layout where conventions could be split into reference files.
Suggestions
State each core policy once and cross-reference it: the 'inbound links live outside PR_SCOPE_FILES' rule and 'No guessing' are each repeated in 4–5 sections; one canonical statement plus links would cut significant length.
Move the Conventions sections (aliases, link style, shortcodes, fragments, external URLs) into a references/ file (e.g. references/conventions.md) and keep SKILL.md as the phase procedure plus a pointer, closing the gap with the promised reference.md mechanism.
Provide a concrete example sweep command (e.g. an actual rg invocation with a sample old path) so the sweep step is copy-paste ready rather than pattern-descriptive.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly project-specific policy Claude would not know (alias collision rules, List 1/List 2 split, Hugo permalink case sensitivity), so it avoids explaining known concepts. However, key policies are restated many times — 'inbound stragglers are often in files the PR never touched' appears in the Agent procedure, Modes, Phase 0.5, and Phase 2, and 'No guessing' is repeated in at least five places — so it could clearly be tightened. Not level 2 because the padding is redundancy of genuinely needed rules, not generic explanation; not level 4 because the repetition is pervasive rather than minor. | 3 / 5 |
Actionability | Concrete executable guidance throughout: 'git diff --name-only main...HEAD', 'BASE=$(git merge-base <target-branch> HEAD)', 'docker buildx bake validate', a real script link ([scripts/scope-pr-files.sh]), and named search trees and URL forms to sweep. Not level 5 because the sweep instructions themselves are descriptive patterns ('path segments that identify the old file') rather than a copy-paste ready command template, and the promised 'reference.md' table storage is conditional rather than provided. | 4 / 5 |
Workflow Clarity | The sequence is explicit and mandated ('Run in order (mandatory for agents)' steps 1–5), phases 0→3 are cleanly ordered, and there is a Definition of done with validation ('docker buildx bake validate' plus a re-sweep) and a true feedback loop in Phase 3 (validate user answer → warn on failure → ask again → repeat until pass or defer). List 1/List 2 checklists cover the batch-edit risk. This matches the top anchor including validation checkpoints and error-recovery loops. | 5 / 5 |
Progressive Disclosure | Structure is good: clear section headers, an explicit run order, and the only bundle file (scripts/scope-pr-files.sh) is real and clearly linked with an honest scope caveat. A 'Progressive disclosure' section explains when to externalize large mapping tables. Not level 5 because nearly all convention detail (~370 lines) is inlined in SKILL.md with no references/ split, and the 'reference.md' mechanism is described but not present in the bundle; it sits above level 3 since what is present is well-organized and references are clearly signaled. | 4 / 5 |
Total | 16 / 20 Passed |