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 well-structured long-running orchestration skill: fully phased, with preflight validation, per-root-cause retry budgets, explicit escalation criteria, and verified bundle scripts invoked by path. The deductions are localized — mangled command prose in one Phase 0 bullet, unstated mechanics (state file, trailer convention), and inlined troubleshooting history that belongs in a reference file.
Suggestions
Fix the Phase 0 Python bullet: the `uv python list --all-versions | grep cpython-<python>-` command is currently interleaved with the 'primary must also differ from every other Python in the image' prose, making the executable command unreadable — split into the command plus a separate note.
Move the 'Known failure patterns' section into references/troubleshooting.md and reference it one level deep from Phase 4, keeping the loop-time decision rules (transient vs real, stop conditions) inline.
Make the Phase 2 state file concrete (exact scratchpad path and format) and state the repo's PR/commit trailer convention instead of only naming it.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and almost entirely repo-specific operational knowledge Claude cannot know (image names, selector pins, failure signatures, stop conditions) — not padded explanation of known concepts. But there are trimmable spots: the 'Known failure patterns' section carries historical narrative (e.g. the terra/GDAL/bookworm history and 'The Debian image is now trixie'), and several pinned version numbers (pyenv 3.13.0, conda 3.12.10, R 4.4.2/4.4.1) are time-sensitive state inline in Phase 0. Fits 'Efficient; minor instances of over-explanation that could be trimmed' — not the every-token-earns-its-place level of a 5. | 4 / 5 |
Actionability | Mostly copy-paste executable: exact `gh auth status`, `git -C "$REPO" switch -c update-images/<tag>`, curl HEAD-request checks, `bash <dir>/scripts/dispatch-job.sh <branch> <tag> [os]`, `gh api -X PATCH repos/<owner>/<repo>/pulls/<n> -f body=...`. Minor gaps keep it below 5: Phase 2's state file has no concrete path or mechanism ('Create a state file in the scratchpad'), 'Commit the end-of-message PR/commit trailer convention used in this repo' never states what that convention is, and the Phase 0 Python bullet is mangled — prose ('The primary must also differ from every other Python in the image...') is interleaved inside the `uv python list --all-versions ... | grep cpython-<python>-` command, so the executable command cannot be read cleanly. | 4 / 5 |
Workflow Clarity | Phases 0–5 are an explicitly sequenced orchestration with validation up front ('Run and confirm all pass before changing anything', 'Verify each version that changes exists before you burn build minutes'), explicit feedback loops (Phase 4 diagnose → classify by failure signature → fix → re-dispatch), bounded retry budgets per root cause, unambiguous stop conditions ('fix_attempts reaches 3 for the same failure signature... OR transient_retries reaches 5'), and checklists (PR checklist boxes, TodoWrite list mirroring the 7 jobs). This matches the level-5 anchor including error-recovery feedback loops and checklists. | 5 / 5 |
Progressive Disclosure | Executable logic is correctly externalized: all 7 referenced scripts (bump-node-version.sh, bump-interpreter-versions.sh, bump-selector-pins.sh, retag-consumers.sh, bump-ppm-snapshot.sh, dispatch-job.sh, wait-for-runs.sh) exist in scripts/ and are invoked by path rather than inlined, and the body is well-sectioned with clear headers. Minor gap: the ~45-line 'Known failure patterns' subsection is decision-support detail that could live in a references/ file one level deep, leaving the body a leaner orchestration overview — 'Good structure; most content is appropriately placed; references mostly clear; minor organization gaps'. | 4 / 5 |
Total | 17 / 20 Passed |