Content
85%Weight 40%Scale 1-3Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured, highly actionable orchestration spec with clear wave sequencing, explicit validation checkpoints, and properly split bundle references. Its one weakness is repetition of the advisory-regime invariants across multiple sections, which inflates length without adding new guidance.
Suggestions
Consolidate the advisory-regime statements: state the 'no verdict / no gate / panel is advisory' invariant once in 'Architecture invariants' and reference it from Waves 3-4, the Output contract, and Gotchas rather than restating it verbatim each time.
Trim the Gotchas section of items that rehash invariants already covered above (e.g. blocker-veto and calibrated-severity are restated), keeping only the genuinely new pitfalls like spec-drift across count sites and per-byte ASCII enforcement.
Consider moving the full Wave 3 panelist prompt fragments into an asset (e.g. assets/panelist-prompt.md) so the body stays a lean overview and the prompt text lives one level deep with the other bundle materials.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient and free of general-knowledge padding, but the advisory regime ('no verdict', 'does not gate merge', 'panel is advisory') is restated across the intro, architecture invariants, Wave 3, Wave 4, Output contract, and Gotchas, and several gotchas rehash invariants already stated above. Not 3 because the repetition could be tightened; not 1 because there is no explanatory fluff about concepts Claude already knows. | 2 / 3 |
Actionability | Highly concrete guidance: numbered waves, exact task invocations, exact paths, the literal marker 'apm-spec-guardian: new-version', line thresholds ('< 50 lines'), and the exact label 'spec-review' to sweep via remove-labels. Instruction-only but specific and copy-ready per the code_vs_instruction_skills note. | 3 / 3 |
Workflow Clarity | Waves 0→6 are clearly sequenced with a topology diagram and explicit validation checkpoints (schema-validate each panelist return, re-spawn max 2 attempts, re-spawn synthesizer once on schema failure, mandatory linter before render, loop budgets with exhaustion semantics). Feedback loops are present for the parallel/batch and PR-state-write operations. | 3 / 3 |
Progressive Disclosure | Overview body points one level deep to real, verified bundle files — assets/panelist-return-schema.json, assets/synthesizer-return-schema.json, assets/linter-checklist.md, assets/comment-template.md — each clearly signaled by role. No nested 2+ level reference chains within the bundle; content is appropriately split between the orchestration overview and the asset files. | 3 / 3 |
Total | 11 / 12 Passed |