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 concrete, well-validated orchestration procedure whose commands, exit codes, and recovery paths are copy-paste ready and whose checkpoints are explicit. Its cost is length and repetition: motivational rationale, stale-prone statistics, and a triple-explained attribution mechanism push it past what the orchestrator's own 'context is the scarce one' doctrine allows.
Suggestions
Move the time-sensitive repo statistics ("64% of this repository's recorded token spend currently sits in that anonymous HEAD pool", "85.8% of subagent spend today") into references/gotchas.md or the session-metrics wiki page, keeping a one-line summary in the body — the numbers will silently go stale and they justify rather than instruct.
Consolidate the TASK-BRANCH explanation, which is given in full in the Precondition warning, again as Step 3's first dispatch bullet, and again in the closing-summary rules, into one normative statement plus short back-references.
Trim the Precondition section's three-paragraph rationale for preferring main/ over the bare root to one or two lines — the commands, the expected outputs, and the failure message already carry the operational content.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and operational — it never explains concepts Claude already knows — but it is not lean: the precondition section spends three paragraphs justifying why main/ beats the bare root, the TASK-BRANCH mechanism is explained fully three times (warning block, Step 3 first bullet, closing-summary rules), and time-sensitive repo statistics ("64% of this repository's recorded token spend currently sits in that anonymous HEAD pool", "It is 85.8% of subagent spend today") are inlined where they will silently go stale. That is more than the minor trimmable over-explanation of the 4 anchor, but well above the generic-padding of a 2. | 3 / 5 |
Actionability | Nearly everything is copy-paste executable: exact fetch refspecs ("git -C /Users/ac/.work/osn.git fetch origin '+refs/heads/main:refs/remotes/origin/main'"), worktree creation ("git worktree add … -b <prefix>/<dir> origin/main"), gh api checks with --jq filters, "bash scripts/wait-pr.sh <n> 30 # exit 0 done, 1 needs action, 2 no verdict by the deadline, 3 cannot answer", and a fully specified ORCHESTRATE.md block template with an example. The common cases are covered with specific commands and exit-code contracts. | 5 / 5 |
Workflow Clarity | The sequence is explicit (Step 00 → 0 → 1–5 per task, with adoption and subagent-death variants), validation checkpoints appear at every boundary ("No subagent's stated verification counts" mechanical checks before reading a report, "test -e every path a dispatch names", gates and premise checks before dispatch), and error-recovery feedback loops are enumerated (red check → shepherd → fix subagent → re-poll; DIRTY/BEHIND → rebase → force-with-lease; merge-queue group failure → regenerate migration). Every wait names terminal states and a deadline, matching and exceeding the explicit-validation anchor. | 5 / 5 |
Progressive Disclosure | The one bundle reference is real and well used: "The full table, with the reason behind each, is `references/gotchas.md`" keeps only the six costliest gotchas inline — genuine, working progressive disclosure — and external pointers (wiki pages, scripts/wait-pr.sh, .claude/agents/shepherd.md) are one level deep and clearly signaled. It falls short of the 5 anchor because the ~440-line body also inlines four auxiliary procedures (adoption, subagent death, question handling, the wait policy) that could partly live in reference files, leaving the main loop to carry them. | 4 / 5 |
Total | 17 / 20 Passed |