Content
56%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 is a well-sequenced operational specification with explicit verification and failure handling, but it is held back by duplicated sections and by delegating its most actionable material (execution protocol, method selection, templates) to reference files that are not present in the bundle. As shipped, a reader following the references cannot actually reach the skill's operating instructions.
Suggestions
Merge the duplicated sections: fold "Intent signature" into "When to use", replace the prose output bullets with the `outputs:` yaml block (or vice versa), and consolidate "Dependencies" with the "References" list.
Ship the missing bundle files — resources/execution-protocol.md, methodology-selection.md, stakeholder-synthesis.md, output-templates.md, api-evolution.md, migration-patterns.md, checklist.md, and _shared/conditional/diagram-engine.md — or remove/inline their content, since 7 of 12 referenced paths resolve to nothing.
Add a short inline decision rule for choosing among Diagnostic, Recommendation, Design-Twice, ATAM-style, CBAM-style, and ADR modes so the skill stays actionable when methodology-selection.md is unavailable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is operational rather than teaching known concepts, but contains clear duplication: "When to use" restates "Intent signature" almost verbatim, the six prose output bullets are repeated in the `outputs:` yaml block, and "Dependencies" largely repeats the "References" section. Mostly efficient, but these padded sections could be tightened — short of anchor 2's pervasive verbosity, above anchor 4's minimal trimming. | 3 / 5 |
Actionability | There is concrete guidance (exact artifact paths `docs/decisions/*.md`, `.agents/results/architecture/`, the `architecture.adr-complete` recording step, and supersede-don't-contradict rules), but the executable detail — "resources/execution-protocol.md for workflow", "resources/methodology-selection.md for method choice", "resources/output-templates.md" — is delegated to files absent from the bundle, so key execution details are missing in practice. This exceeds anchor 2's high-level-only hints but is incomplete versus anchor 4. | 3 / 5 |
Workflow Clarity | A clear Entry → PREPARE/ACQUIRE/REASON/VERIFY/FINALIZE scene sequence with transitions, a VERIFY step ("Check assumptions, validation steps, and fit against constraints"), and an explicit "Failure and recovery" section provides most checkpoints. It falls short of anchor 5 because validation specifics ("resources/checklist.md (run before handoff)") point to a file that does not exist in the bundle, leaving checkpoint content implicit. | 4 / 5 |
Progressive Disclosure | References are clearly signaled one level deep with stated purposes ("Method selection: resources/methodology-selection.md", "API evolution patterns...: resources/api-evolution.md"), but 7 of the 12 referenced paths are missing from the bundle — all six `resources/` files plus `_shared/conditional/diagram-engine.md` — so navigation dead-ends on the core operational documents. Signaling exceeds anchor 3, but the broken disclosure chain is more than the minor organization gaps of anchor 4. | 3 / 5 |
Total | 13 / 20 Passed |