Content
77%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 orchestration skill with an exemplary workflow: explicit gates, remediation feedback loops, a hard escalation cap, and clean one-level-deep progressive disclosure into a real reference file. The main cost is redundancy — end-of-run verification and gate-failure handling are each stated multiple times — which inflates the token budget without adding guidance.
Suggestions
Merge 'Final Verification' and 'After Implementation' into one section — both instruct running the full test suite and verifying acceptance criteria.
Consolidate gate-failure handling into a single location (the loop's step f, 'Gate Failures', and Remediation step 5 currently repeat the same STOP/escalation rules three times).
Inline a one-line pointer to the agent prompt template in workflow-detail.md at the 'Dispatching Agents' step, so the orchestrator knows where the dispatch prompt comes from without scrolling.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient orchestration prose, but genuine duplication: 'Final Verification' and 'After Implementation' both mandate running the full test suite and verifying acceptance criteria, and gate-failure handling is stated three times (loop step f, 'Gate Failures', and Remediation step 5). Not 4: the redundancy exceeds 'minor instances that could be trimmed'. | 3 / 5 |
Actionability | Concrete tool calls (beads:ready, beads:show, beads:close, beads:create, beads:list), an explicit label taxonomy, title templates like 'P{N}: Remediate — {Phase Name} (attempt {M})', and a worked progress-report example. Not 5: the core loop is control-flow pseudocode and the agent prompt templates are deferred entirely to workflow-detail.md, leaving minor gaps at dispatch time. | 4 / 5 |
Workflow Clarity | Clear sequence (identify epic → orchestration loop → report progress → final verification) with explicit validation gates (RED/GREEN), a remediation feedback loop capped at 2 attempts, STOP-and-escalate rules, and a 'What Not to Do' checklist. Matches the top anchor: explicit validation steps, error-recovery feedback loops, and a checklist for a complex process. | 5 / 5 |
Progressive Disclosure | The body is a well-organized overview with the core loop inline, and details (agent prompt templates, dispatch procedures) are split into a single clearly-signaled reference (references/workflow-detail.md), verified to exist and only one level deep with no nested references. Not 4: the split and navigation are exactly appropriate for the content volume. | 5 / 5 |
Total | 17 / 20 Passed |