Content
75%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 domain reference: lean tables, concrete commands, and workflows with real validation gates. Every dimension sits at anchor 4 due to small, identifiable gaps — repeated facts, unspecified gate details, no explicit error-recovery loops, and advertised-but-absent optional reference files.
Suggestions
State the embed.go fact once (in the Key Source Paths table) and reference it from the Build Cycle, and drop the duplicated 'Never edit .claude/ or .moai/ directly' sentence since step 1 of the cycle already implies it — this would push conciseness to anchor 5.
Briefly enumerate the sync-auditor's four scoring dimensions (or link to where they are defined) so the gate in the Add-a-SPEC workflow is actionable without external context.
Add explicit error-recovery branches to the Template-First cycle (e.g. 'if the neutrality audit fails, fix the template and re-run make build + moai update'), or move the delegation map into a small reference file to back the frontmatter's level_3_optional claim.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and factual — tables, a path map, and terse numbered steps — with no explanations of concepts Claude already knows. It fits anchor 4 rather than 5 because of repeated facts: "//go:embed all:templates" appears three times (Architecture, Key Paths, Build Cycle) and the Template-First rule is stated twice in the same section. | 4 / 5 |
Actionability | Mostly executable guidance with concrete commands: `make build`, `moai update`, `./moai init /tmp/test-project`, `go test ./internal/template/... -run TestTemplateNeutralityAudit`, and `/moai plan "<description>"`. Minor gaps remain, e.g. "sync-auditor 4-dimension gate" never states what the four dimensions are, and the delegation-map entries name agents without their prompts or paths. | 4 / 5 |
Workflow Clarity | Each workflow is a clear numbered sequence with explicit validation checkpoints (`go test` neutrality audit, "Verify the local .claude/ .moai/ reflects the template", plan-auditor audit gate, human approval gate), so the destructive/batch cap does not apply. It stops short of anchor 5 because no error-recovery feedback loops (if-fails-then-fix-and-retry) are spelled out. | 4 / 5 |
Progressive Disclosure | No bundle files (references/, scripts/, assets/) exist, and the single SKILL.md is well organized into clearly headed sections with a Cross-References section listing one-level-deep, clearly signaled project paths. Minor gaps: the frontmatter advertises level_3_optional with no optional reference files present, and dense inline material like the delegation map could live in a reference file. | 4 / 5 |
Total | 16 / 20 Passed |