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 delivers an exceptionally rigorous, validation-heavy workflow with executable gh CLI commands, precise read-back verification, and fail-closed error handling. Its weaknesses are density and redundancy — rules are restated across sections, sentences are over-stuffed, and repository-specific policy is inlined rather than offloaded to the reference file.
Suggestions
Deduplicate rules repeated across Hard Rules, Approved Catalog Gate, and Execution Steps (duplicate search, label permissions, protected-label handling) into one canonical section and cross-reference it.
Replace the step-6 label-expansion table with a one-line rule (append one `--label "$PERMITTED_LABEL"` pair per permitted label, none if zero) and split long semicolon-chained sentences into short bullets.
Move the repository-specific gentle-ai catalog policy (the two paragraphs naming github.com/Gentleman-Programming/gentle-ai) into a reference file like references/delegated-workflow-actions.md to slim the generic body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | No tokens are spent explaining concepts Claude already knows, but rules are restated across sections (duplicate search in Hard Rules and Execution Steps, protected-label and capability rules in both Hard Rules and Approved Catalog Gate), the step-6 table overspecifies trivial `--label` token expansion, and long semicolon-chained sentences could be tightened. It is not 4 because the redundancy exceeds minor over-explanation; it is not 2 because there is no padding or filler — every sentence carries operative rule content. | 3 / 5 |
Actionability | Concrete executable `gh` commands with exact flags cover the main operations (label enumeration via `gh api`, `gh issue list --state all`, `gh issue view --json`, `gh issue create --body-file`, comment read-back with identity verification). It is not 5 because derivation of key inputs like `$QUERY`, `$TITLE`, and the "reviewed answers" is left abstract and the conforming-equivalent comment path never shows its command; it is not 3 because the shown commands are real, executable, and span the critical mutation and verification cases. | 4 / 5 |
Workflow Clarity | Nine explicitly sequenced steps with validation checkpoints at every phase: target identity verified from `DISCOVERY_FILE` and `READBACK_FILE`, exact title/body comparison after normalization, and a fail-closed `confirmed | no_write | unknown` classification where `unknown` halts all later mutations and retries. It is not 4 because no checkpoint gaps are evident — this is a write-operation skill whose validation is thorough, so the missing-validation cap does not apply. | 5 / 5 |
Progressive Disclosure | The single bundle file `references/delegated-workflow-actions.md` exists, is clearly signaled as normative ("read ... completely and follow it. It is normative, not optional background"), and is one level deep (87 lines, no nested references). It is not 5 because the main body inlines a large mass of dense policy detail (Hard Rules, Approved Catalog Gate) that could be split out, leaving the overview heavier than an overview should be; it is not 3 because sections are well-organized and the reference path is explicit rather than buried. | 4 / 5 |
Total | 16 / 20 Passed |