Content
78%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-expert skill: concrete worked example, ordered workflow with a green-before-layering gate, and exemplary one-level-deep progressive disclosure into three real reference files. The only weaknesses are minor — a few tokens spent defining known concepts and per-step validation checkpoints that are implicit rather than explicit.
Suggestions
Trim known-concept explanations: drop the Fowler definition quote ('rebuild application state from scratch by replaying events in order') and the 3-line rationale intro; start directly at the test patterns.
Add a per-step validation cue in 'How to use' (e.g. 'run the aggregate suite; proceed to projections only when replay-determinism and snapshot tests are green') so each layer has an explicit checkpoint.
Inline one compact assertion snippet for the two most common non-base checks (snapshot-at-N == replay-to-N and a mixed-version upcast replay) so the main file is actionable without opening a reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and test-specific ('assert new_events == [OrderConfirmed(order_id="o1")]', the anti-patterns table, 'Test each projection off one stream independently'), but has minor over-explanation of concepts Claude already knows, e.g. quoting Fowler's definition 'rebuild application state from scratch by replaying events in order' and the 3-line rationale intro. These could be trimmed without losing guidance. | 4 / 5 |
Actionability | The worked example is a complete, concrete test function ('history = [OrderCreated(...)] ... assert state_a == state_b') and the projection section names specific assertions with a parameterized example ('ProductPriceChanged → {"sku1.price": 120}'). Minor gaps remain: snapshot equivalence, upcasting, and swap mechanics are named but their code is deferred entirely to the references rather than shown or sketched inline. | 4 / 5 |
Workflow Clarity | 'How to use' gives a clear 6-step sequence with an explicit gate ('Once this base test is green, layer on the operational checks') and the anti-patterns table maps failures to fixes. Minor validation gaps: steps 3-6 have no per-step run/verify checkpoint and no explicit test-run command is given. | 4 / 5 |
Progressive Disclosure | The body is a ~145-line overview that splits deep material into three real, one-level-deep bundle files, each clearly signaled with its scope in place ('see [references/snapshot-versioning-projections.md]', 'the deadline + poll + assert pattern in [references/convergence-windows.md]') and summarized again in the References section. Verified all three referenced files exist with no nested references inside them. | 5 / 5 |
Total | 17 / 20 Passed |