Content
85%Reviews 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 specification-writing guide with strong workflow gating, checklists, and a properly signaled one-level-deep reference. Its main weakness is length — several philosophical passages restate points and could be trimmed without losing guidance value.
Suggestions
Tighten the Core Philosophy and Maintainer-Time Contract prose: the six philosophy bullets and surrounding reframes overlap the structural guidance that follows, so collapsing them would cut tokens without losing actionability (conciseness).
Consolidate repeated framing such as "A spec is a launching pad, not a script to follow" and the closing sweet-spot sentence, which restate the opening philosophy (conciseness).
Consider moving the long Catalogs and Call Sites before/after worked examples into a reference file, keeping only the pattern explanation inline, to further reduce the main-file footprint (progressive_disclosure).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~430-line body avoids explaining concepts Claude already knows and is mostly prescriptive, but carries redundant philosophical framing (e.g., "A spec is a launching pad, not a script to follow" restating the Core Philosophy bullets) and prose that could be tightened. It is efficient but not lean enough that every token earns its place, so it lands at 2 rather than 3 and is well above the padded score-1 anchor. | 2 / 3 |
Actionability | It provides concrete, copy-paste-ready templates for every section, a concrete naming convention ("specs/YYYYMMDDThhmmss-feature-name.md"), decision-class tables, and verbatim before/after call-site examples. Per the instruction-only scoring note, the absence of executable code is not penalized because the guidance is highly actionable. | 3 / 3 |
Workflow Clarity | The spec-writing process is sequenced via the document structure, gated by the one-sentence-test ("the spec is not ready"), and includes an explicit Build/Prove/Remove wave ordering with a verification checkpoint ("Do not schedule deletion before verification passes") plus checkbox checklists. This matches the score-3 anchor of clear sequence with explicit validation steps and feedback loops. | 3 / 3 |
Progressive Disclosure | The References section gives condition-based, one-level-deep loading (decision-hygiene.md, verified to exist with no nested references) and the main file keeps core templates inline while pushing deeper failure-mode detail to the reference. It matches the score-3 anchor of a clear overview with well-signaled one-level-deep references and easy navigation. | 3 / 3 |
Total | 11 / 12 Passed |