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.
The body is lean, actionable, and well-organized, giving Claude concrete boundaries, tooling, and verification commands without explaining concepts it already knows. The main gaps are the absence of a concrete example test and an explicit validate-fix-retry feedback loop.
Suggestions
Add a short, copy-pasteable example test (e.g. a fake-adapter behavior test) to make the actionability fully concrete.
Make the Verification flow's error-recovery loop explicit (e.g. 'If ruff/pytest fail: fix and re-run until green') to reach a 5 on workflow_clarity.
Trim the minor overlap between the 'Avoid' bullets and the 'Prefer Fakes Over Mocks' / 'Core Principle' sections to tighten conciseness.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes competence — no basic explanations of pytest or testing concepts — with every section earning its place; minor duplication between the 'Avoid' list and earlier principles keeps it just short of a 5. | 4 / 5 |
Actionability | Provides concrete, executable guidance: a boundaries table, specific tooling stack (pytest, pytest-asyncio, respx, pytest-textual-snapshot), and copy-paste verification commands ('uv run ruff format .', 'uv run pytest <test-path>'); lacks an actual example test, which would make it fully copy-paste ready. | 4 / 5 |
Workflow Clarity | The 'Legacy Or Refactor Workflow' is a clear 5-step sequence and the 'Verification' section gives an ordered format/check/test/pyright flow with an implied fix loop; checkpoints are present but the error-recovery feedback loop is implicit rather than explicit. | 4 / 5 |
Progressive Disclosure | Well-organized with clear section headers (Core Principle, Boundaries, Fakes, Workflow, Test Shape, Avoid, Verification) and no external references needed; at ~70 lines with all content inline it is well structured but slightly above the under-50-line simple-skill exception. | 4 / 5 |
Total | 16 / 20 Passed |