Content
75%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 an efficient, highly actionable runbook with a well-sequenced workflow and real validation checkpoints. Remaining gaps are small: undefined placeholder variables, an inconsistent branch-prefix convention between steps 2 and 5, and a duplicated notice block.
Suggestions
Define SOURCE_PATH/<agent> once at the top and use one consistent branch-prefix convention (step 2's agent/ vs step 5's fix/) so the commands are copy-paste ready.
Remove the duplicated IMPORTANT notice block in step 4 by showing the full template once with the notice as its opening lines.
Reconcile the --force-with-lease constraint with the actual push step, either adding the flag to the workflow or dropping the unused rule.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and command-first with no re-explanation of concepts Claude already knows; the only notable redundancy is the IMPORTANT notice block duplicated verbatim in step 4. It is not anchor 5 because that duplicated block (and the repeated gh api user lookups) could be trimmed, and not anchor 3 because there is no padded explanatory prose. | 4 / 5 |
Actionability | Concrete executable bash (gh auth status, gh pr list with --head filter, git checkout -b, gh pr create --draft --body-file) and an exact PR body template are provided. It is not anchor 5 because placeholders like ${SOURCE_PATH}, <source_path>, and <agent> are never defined, and step 5's BRANCH="fix/<descriptive-name>" contradicts step 2's agent/ naming scheme, so it is not fully copy-paste ready. | 4 / 5 |
Workflow Clarity | A clear six-step sequence with explicit checkpoints: prerequisite verification (step 1), duplicate-PR detection with early exit (step 3), and outcome logging with a skip path (step 6). It is not anchor 5 because a constraint references 'git push --force-with-lease' which never appears in the workflow's commands, leaving a minor validation gap between the stated rule and the executable steps. | 4 / 5 |
Progressive Disclosure | A single well-sectioned file with clear headers (When to invoke, Steps, Per-repo upstream table, Important constraints) and no bundle files to navigate. It is not anchor 5 because at ~160 lines the PR body template and per-repo table are candidates for a one-level-deep reference file, keeping it just above the simple-skill threshold; it is well above anchor 3 since nothing is buried and all structure is clear. | 4 / 5 |
Total | 16 / 20 Passed |