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.
A well-structured orchestration skill with an explicitly gated four-phase workflow and unusually concrete guidance (named paths, verbatim prompts, explicit output schemas). The main costs are redundancy — the behaviour-preserving §10 invariant and the finds-designs-doesn't-implement boundary are each stated multiple times — and references to sidecar files that are not shipped alongside the SKILL.md under review.
Suggestions
State shared invariant §10 once (e.g., in the opening blockquote) and reference it by number elsewhere; the same applies to the 'proposes and designs, does not implement' boundary, which is currently given in both the blockquote and the 'What this skill does not do' section.
Trim the inline glossary to the terms the body actually uses that are non-obvious (Depth, Seam, Locality, deletion test) and defer full definitions to LANGUAGE.md, which is already linked as the source.
Ensure the referenced sidecar files (LANGUAGE.md, PRESENTING.md, DEEPENING.md, INTERFACE-DESIGN.md and the ../grill-with-docs/ format files) ship with the skill bundle so the one-level-deep reference structure is navigable as written.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly dense and project-specific, but the same invariants are restated: shared invariant §10 appears three times (the opening blockquote, "What this skill does not do", and "Hand off"), and "finds and designs; it does not implement" appears twice (blockquote §7 and the not-do section). The inline glossary definitions of "Module", "Interface", and "Implementation" also overlap with what LANGUAGE.md already carries, so the body could be tightened without losing information. | 3 / 5 |
Actionability | For an instruction-only skill the guidance is fully actionable: exact file paths to read first (docs/domain-glossary.md, docs/adr/, constitution/local-engineering.md, scripts/agents.config.sh), a named spawn prompt (.agents/prompts/cheap-reads.md), a concrete output convention (`<tmpdir>/architecture-review-<timestamp>`), an explicit card schema with enumerated fields and recommendation-strength labels, verbatim questions to ask ("Which of these would you like to explore?"), and precise rules for when to offer an ADR or update the glossary. | 5 / 5 |
Workflow Clarity | The four phases (scope/explore, present candidates, grilling loop, hand off) are clearly sequenced with explicit checkpoints and gates: read glossary and decision records before proposing, "Do NOT propose interfaces yet", stop and ask which candidate to explore after writing the report, and "The session ends at an agreed design, not at a diff". The grilling loop with inline side-effect rules provides the feedback structure, and no destructive or batch operations apply. | 5 / 5 |
Progressive Disclosure | The body is a genuine overview that pushes detail to well-signaled, one-level-deep references — "Full definitions in [LANGUAGE.md]", "[PRESENTING.md] carries that contract in full — the card layout, the visualisation patterns", "[DEEPENING.md] is how to classify the dependencies" — each stating what the file covers. However, none of the referenced files (LANGUAGE.md, PRESENTING.md, DEEPENING.md, INTERFACE-DESIGN.md, ../grill-with-docs/GLOSSARY-FORMAT.md, ../grill-with-docs/ADR-FORMAT.md) are present in the bundle being evaluated, so the split and navigation cannot be verified against actual files. | 4 / 5 |
Total | 17 / 20 Passed |