Content
52%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 well-structured with a clear redirect section, a legible phase-mapping workflow, explicit validation gates, and mostly well-signaled one-level-deep references. Its main weaknesses are heavy repetition of the deprecation message and verbose internal-policy commentary that inflate token cost without operational value, plus deferral of key execution detail to out-of-bundle files.
Suggestions
Consolidate the deprecation notice into a single canonical statement — it is currently repeated across the title notice, opening blockquote, @MX:NOTE comment, ATTRIBUTION block, and redirect section.
Move the long policy-supersession HTML comment (the @MX:NOTE block) into a reference file or trim it to its operative sentences; it is internal contract rationale, not reader-facing guidance.
Resolve the orphan 'references/hrn-003-hierarchical-scoring.md' — either cite it alongside hierarchical-scoring.md or remove it, since it is never referenced from the body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The deprecation message is restated at least five times (title notice, opening blockquote, the long @MX:NOTE HTML comment, the ATTRIBUTION block, and the 'v4 Redirect' section), and the inline policy-supersession comment is dense internal-contract rationale that adds no operational value for a reader. Not 1: the legacy body is deliberately preserved under an explicit 'HISTORICAL REFERENCE' separator and time-sensitive data (versions, 2026 dates, effectiveness figures) sits inside that marked deprecated section, which the guidelines treat as acceptable placement. Not 3: the repetition of the redirect message and the oversized inline comment are several padded sections, not just occasional tightening opportunities. | 2 / 5 |
Actionability | There is concrete guidance — explicit commands ('/moai:harness <natural-language request>', '/moai:harness list|edit|remove <name>', '/harness:<name>'), artifact paths, the phase-mapping table, and [HARD] contracts with exact emission rules. Not 4: key operational detail is deferred to files outside this skill ('harness-builder.md', 'project/meta-harness.md' § 6.4.1, '.claude/rules/moai/…') that a reader cannot act on from the body alone, and no example of the actual emission template is inlined. | 3 / 5 |
Workflow Clarity | The 7-phase workflow is clearly sequenced with a per-phase inputs/outputs mapping table and phase summaries, and validation is explicit: the Phase 6 Sprint Contract (4 dimensions, 0.75 pass threshold, FROZEN floor 0.60) plus the 'moai doctor harness' smoke gate with named failure conditions (empty description, dangling skills: reference, missing skills: key) forms a real checkpoint with feedback. Not 5: recovery steps after a gate failure and the actual phase-execution mechanics are referenced elsewhere rather than stated, leaving minor validation-loop gaps. | 4 / 5 |
Progressive Disclosure | Structure is good: the body is organized into clear sections, and detail is pushed to one-level-deep reference files cited with descriptive link text ('references/seven-phase-workflow.md' cited for the phase walkthrough, 'references/agent-cross-references.md' for the agent inventory, 'references/hierarchical-scoring.md' for Phase 3b) — all three verified to exist. Not 5: 'references/hrn-003-hierarchical-scoring.md' is present in the bundle but never referenced from the body, and some dense contract material (the namespace storage tables and the supersession comment) is inlined rather than split out. | 4 / 5 |
Total | 13 / 20 Passed |