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 strong orchestration body: unambiguous sequencing, exact commands and prompts, and error-recovery loops at every phase of the batch pipeline, with well-signaled real reference files. Its weakness is token efficiency — repeated dispatch boilerplate, re-stated reference content, and a large inline decision gate that should itself be a reference file.
Suggestions
Extract the Complex Phase Upgrade Gate (Step 3.5c, ~60 lines) into a reference file (e.g. references/complex-upgrade-gate.md) and keep only the filter and 'read the gate reference' instruction inline, mirroring how plan-shipping.md is handled.
Replace the three verbatim repetitions of the agent-dispatch model boilerplate with a single defined convention (e.g. a one-line 'Dispatch convention: pass the model from .arness/agent-models/code.md per ensure-config.md' stated once in Step 2.7, then referenced as 'dispatch per convention').
In Step 2.5b, drop the re-stated six scoring steps and keep only 'apply the scope router criteria from scope-router-criteria.md per feature, then map to tier (0-4 swift, 5-12 standard, 13-20 thorough)', trusting the referenced file for the detail.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body contains no educational padding (it never explains concepts Claude already knows) and its tables/diagrams are token-efficient, but it is noticeably repetitive and over-inlined: the dispatch boilerplate 'passing the model from `.arness/agent-models/code.md` as the `model` parameter (see ... "Dispatch convention" for fallback)' appears verbatim three times (Steps 2.7, 3d, 3.5b), Step 2.5b re-states the six scope-router scoring steps that already live in scope-router-criteria.md ('The same scope router used by arn-planning (Step 3C) is applied here per feature'), and the ~60-line Complex Phase Upgrade Gate branches in full procedural detail inline. This fits 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than the efficient-but-trimmable anchor 4, and is well above the verbose anchor 2 since nothing is concept-explanation filler. | 3 / 5 |
Actionability | Fully executable guidance throughout: exact commands ('gh issue list --state open --limit 20 --json number,title,labels', 'git checkout -b plans/<date>-batch'), exact AskUserQuestion prompts with complete option sets, concrete naming conventions ('SWIFT_<kebab-case-name>', 'PLAN_PREVIEW_<spec-name>.md'), explicit output paths, and precise retry policies ('Retry that specific feature's batch-analyzer (up to 2 retries) ... after 3 total attempts'). Placeholders like [N] and [Feature Name] are clearly parameterized template slots, not vague directions — this matches the copy-paste-ready anchor. | 5 / 5 |
Workflow Clarity | The multi-step process is clearly sequenced (Steps 0, 1, 1a-1c, 2, 2.5-2.7, 3a-3e, 3.5a-3.5c, 4-6) with explicit validation checkpoints and feedback loops for this batch operation: pre-analysis failure retries with user choice ('Never silently fall back to a degraded flow'), spec-phase error handling with Retry/Skip/Abort, planner failure retry-then-ask, tracker status revert-on-failure ('revert the feature's status from `in-progress` back to `pending`'), plan approval gates before save-plan, and post-pull verification that plans exist on disk. This satisfies the batch-operation feedback-loop requirement and matches the anchor for explicit validation steps with error-recovery loops. | 5 / 5 |
Progressive Disclosure | Structure is good: the two local references are real files (references/backlog-selection.md, references/plan-shipping.md), clearly signaled at point of use ('Read ... and follow its procedure'), one level deep, and cross-skill references are consistently path-qualified under ${CLAUDE_PLUGIN_ROOT}. However, the ~600-line body inlines content that belongs in a reference — most notably the ~60-line Complex Phase Upgrade Gate (3.5c) with its session-memory model and two-tier preference lookup (which even points to preferences-schema.md), and the re-stated scope-router scoring steps of 2.5b — which is why this is 'good structure with minor organization gaps' rather than the cleanly split anchor 5. | 4 / 5 |
Total | 17 / 20 Passed |