Content
63%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, largely actionable overview for a domain-specific SPEC workflow, with explicit validation gates and checklists. Its main weaknesses are duplicated pattern/deprecation content between the Quick Reference and Implementation Guide, and a bundle structure that strands its two largest reference files (examples.md, reference.md) plus one dangling reference path.
Suggestions
Link references/examples.md and references/reference.md from the body (e.g., in the Quick Reference or a Resources subsection), since they hold the majority of the bundle's content but are currently unreachable from SKILL.md.
Fix the dangling reference at line 345: 'worktree-integration.md § Refused Commands in a Worktree-Isolated Session' does not exist in the bundle — either add the file or point at the correct path (likely references/worktree-workflow.md).
Deduplicate the GEARS/EARS pattern tables and the IF/THEN deprecation callout, which each appear in both the Quick Reference and the Implementation Guide; consolidate the repeated '6-month backward-compatibility window' / 'Pre-v3 SPECs' framing into a single legacy-section statement referenced from elsewhere.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with project-specific tables and avoids explaining concepts Claude already knows, but the Quick Reference duplicates the Implementation Guide's GEARS/EARS pattern tables, the IF/THEN deprecation callout appears twice (lines 65 and 85/142), and the '6-month backward-compatibility window' / 'Pre-v3 SPECs (those authored before GEARS became canonical)' framing repeats verbatim 4-5 times. Mostly efficient but could be meaningfully tightened by deduplicating these sections. | 3 / 5 |
Actionability | Concrete, copy-paste-ready guidance is present: '/moai plan "user authentication system"' commands, a full compound-clause GEARS example ('**Where** the project is initialized **While** strict mode is active **When** a SPEC author runs `moai spec lint`...'), exact file paths ('.moai/specs/SPEC-{ID}/spec.md'), the 12-field frontmatter schema, and the '[NEEDS CLARIFICATION: <specific topic>]' marker format. Not a 5 because the six workflow stages are one-line abstractions ('parse natural-language feature description'), the RUN phase is a single compressed arrow-chain sentence, and actual `moai spec lint` invocation is never demonstrated. | 4 / 5 |
Workflow Clarity | The SPEC Workflow Stages table gives a clear 1-6 sequence, and validation checkpoints are explicit: plan-auditor flags 'clarification gate' findings, 'Implementation Kickoff Approval (mandatory human gate) proceeds only after all clarifications are resolved', `moai spec lint --strict`, and a checkbox Verification checklist with feedback loops (question-channel rounds, blocker report for unresolved markers). Not a 5 because stage-level operational detail is deferred to references and the RUN phase reads as a dense run-on, requiring the reader to assemble the full sequence from scattered sections. | 4 / 5 |
Progressive Disclosure | The four linked references (ears-deep-dive, requirement-clarification, worktree-workflow, migration-guide) are clearly signaled one level deep, but the bundle check reveals real navigation gaps: examples.md (31KB) and reference.md (21KB) — the majority of the bundle's content — are never linked from the body, and line 345 points to 'worktree-integration.md § Refused Commands', which does not exist in the bundle. These gaps exceed the 'minor organization gaps' of the anchor above, even though the linked references are well signaled. | 3 / 5 |
Total | 14 / 20 Passed |