Content
48%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 encodes a genuinely rigorous orchestration process with strong sequencing, validation gates, and feedback loops — its workflow design is among the more thorough one could ask for. But it is delivered as a wall of maximally dense abstract prose that wastes tokens, omits the concrete input-contract examples needed to execute it, and keeps far too much detail inlined in SKILL.md instead of the reference files it already demonstrates it can use. The result is a skill that is hard to load, hard to follow, and hard to act on directly.
Suggestions
Move the Handoff Contracts (HC-01 through HC-06), the Small Evidence Gate mechanics, and Requirement Change Detection details into a reference file (e.g., references/handoff-contracts.md), keeping only a summary table of contract keys in SKILL.md
Rewrite rules as short imperative directives with a table or checklist format — e.g., replace the multi-clause sentence on output discipline with "Pass only the contract's canonical field: value entries; added context degrades specialist results" — cutting the body to a fraction of its current size
Add one concrete worked example of a serialized Agent prompt (subagent_type, description, prompt with the declared field: value entries) so the "input contract" guidance is executable rather than abstract
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~40KB body is noticeably-to-severely verbose: nearly every rule is wrapped in abstract qualifiers (e.g., "This output discipline supersedes general-purpose prompt self-containment because added context competes with the specialist's loaded process and can prevent coherent completion") where a fraction of the tokens would carry the same instruction. It avoids explaining concepts Claude already knows, which keeps it above anchor 1, but the padding is extensive — many sections could be cut to a third of their length without losing guidance. | 2 / 5 |
Actionability | Concrete guidance exists — exact field names (`task_file`, `direct_scope`, `governing_sources`, `observable_verification`, `doc_type: ADRBatch`), exact result statuses (`pass`, `stub_detected`, `verification_incomplete`, `blocked`), an explicit commit-trailer format, and named handoff keys (HC-01 through HC-06). However, key details are missing: the "active workflow's input contract" that prompts must serialize is referenced but never shown, and there are no worked examples of an actual prompt or serialized value, so the guidance cannot be directly executed without outside knowledge. | 3 / 5 |
Workflow Clarity | Multi-step processes are clearly sequenced with explicit validation checkpoints: per-scale planning-flow tables, a 4-step per-task cycle with branch handling at each step, a mandatory quality-fix gate before commit, Commit Boundary Check, review-status routing tables, re-run rules, and Review Resolution convergence loops. It stops short of anchor 5 because the dense cross-referencing ("Apply Specialist Result Acceptance" invoked from many scattered places) and long compound sentences make the overall flow hard to follow without re-reading. | 4 / 5 |
Progressive Disclosure | The three bundle references (monorepo-flow.md, review-resolution.md, lite-mode.md) are one level deep, cited by exact path in the body, and listed in a References section with descriptions — good signaling. But the body itself inlines an enormous amount of detail that belongs in reference files (all HC handoff contracts, the Small Evidence Gate mechanics, requirement-change handling), leaving a monolithic ~40KB main file where anchor 4 expects most content appropriately placed. | 3 / 5 |
Total | 12 / 20 Passed |