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.
A well-structured, script-driven multi-stage workflow with strong sequencing, explicit re-verification loops, and a thorough verification section. The main weaknesses are repeated guardrail/dry-run statements and inline policy detail that could be moved to reference files.
Suggestions
Consolidate the repeated never-merge and --dry-run rules into the Hard Guardrails section and reference it once from each stage instead of restating them.
Define $RUN_DIR explicitly (e.g. RUN_DIR="$PAPERCLIP_RUN_SCRATCH_DIR/pr-gardening") where the Stage A command first uses it.
Move the marker-comment templates and Stage D edge-case policy into a references/ file to shorten the main body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body assumes Claude's competence and never explains known concepts, but guardrail statements repeat across sections ("never merge" appears in Hard Guardrails, Stage C, the marker template, and Stage F; --dry-run semantics are restated four times), so minor trimming is possible. | 4 / 5 |
Actionability | Stages A, B, F, and the test section give copy-paste node commands, exact marker syntax, suggested comment bodies, and named API endpoints with headers. Minor gaps: $RUN_DIR is used in commands without a direct definition, and Paperclip API mutations lack full request examples. | 4 / 5 |
Workflow Clarity | Stages A-F are clearly sequenced with explicit validation checkpoints ("Always rerun this stage after any wake", "On every wake, rerun Stage B first"), feedback loops after prepare work, mechanical termination conditions, and a verification section with expected outcome buckets — a strong fit for a batch operation. | 5 / 5 |
Progressive Disclosure | All four referenced script paths (find-candidates.mjs, check-readiness.mjs, render-report.mjs, pr-gardening.test.mjs) exist in scripts/ and are one level deep, and sections are clearly headed. However, all policy detail, guardrail edge cases, and comment templates live inline in a ~170-line file rather than being split into reference files. | 4 / 5 |
Total | 17 / 20 Passed |