Content
48%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 content has a strong process spine — clearly sequenced phases with validation gates, feedback loops, and a verification checklist — but it is padded with concepts Claude already knows and its AST-grep guidance stops at description level without executable examples. As a single-file monolith with no references, it also underuses progressive disclosure.
Suggestions
Cut the sections explaining knowledge Claude already has (coupling/cohesion metric formulas, the Extract/Move/Inline/Rename pattern catalog, the DDD-vs-TDD philosophy comparison) down to one-line pointers, keeping only the skill-specific workflow.
Add one concrete AST-grep rule example (YAML rule plus the `moai ast-grep` command to run it) and one characterization test example, replacing the abstract 'create a rule that...' instructions.
Split the ~410-line body into reference files (e.g., references/analysis.md, references/preservation.md, references/troubleshooting.md) with the body kept as a concise overview pointing to them one level deep.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body explains textbook concepts Claude already knows: coupling/cohesion metric definitions (Ca, Ce, Instability, Abstractness, Distance from Main Sequence), standard Fowler refactoring patterns (Extract Method/Class, Move Method, Inline, Rename), and a DDD-vs-TDD philosophy section; the 'When NOT to Use DDD' point is stated twice in Quick Reference. This matches anchor 2's 'several unnecessary explanations or padded sections' rather than 3's 'some unnecessary explanation'. | 2 / 5 |
Actionability | There is some concrete guidance (5-step characterization-test procedure, incremental commit/revert loop, real paths like `.moai/config/astgrep-rules/` and commands `moai ast-grep`/`moai ast-edit`), but the core transformation guidance is pseudocode-level ('create a rule that identifies the code pattern and rewrites') with no executable AST-grep rule or test examples. Anchor 3's 'some concrete guidance but incomplete; missing key details' fits; anchor 4 requires mostly executable guidance. | 3 / 5 |
Workflow Clarity | The ANALYZE-PRESERVE-IMPROVE sequence is clearly staged with explicit validation gates ('verify all existing tests pass (100% green)' before improving, run tests after each change), feedback loops ('If tests fail, revert immediately', git-stash recovery), and a final verification checklist. Not 5 because several checkpoints are high-level without commands ('Confirm safety net adequacy', 'Assess current test coverage'), matching anchor 4's 'minor validation gaps'. | 4 / 5 |
Progressive Disclosure | Sections are well-organized with clear headers, but this is a ~410-line monolith with no bundle files at all — the DDD/TDD philosophy, refactoring pattern catalog, coupling metric definitions, and troubleshooting are inlined detail that belongs in reference files. Matches anchor 3's 'some structure... content that should be separate is inline'; not 4 because there is no appropriate split into references. | 3 / 5 |
Total | 12 / 20 Passed |