Content
73%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 highly actionable with a well-sequenced, validated workflow and a correct one-level reference file, but it is held back by redundancy — a duplicated step summary and quoted marketing bullets — and by mutmut 2.x/3.x CLI flag inconsistencies in the CI and PR-wrapper snippets.
Suggestions
Remove the 'How to use' numbered summary (or the Step 1-7 headers) — the two duplicate each other point for point — and drop the quoted 'Key features' marketing bullets from the Overview.
Reconcile CLI flags with mutmut 3.x: replace '--paths-to-mutate' and '--max-children' with the 3.x equivalents (source_paths scoping / [tool.mutmut] settings) so the CI and PR-wrapper snippets are actually executable, and align the wrapper script with the prose that says to use source_paths.
Consider offloading the mutator catalog and full CI yaml to a reference file alongside mutmut-pitfalls.md to slim the ~210-line body further.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 7-step 'How to use' summary is fully duplicated by the expanded 'Step 1-7' sections, and the Overview quotes five marketing-style feature bullets ('Interactive terminal based UI', 'Parallel and fast execution') that add no instructional value, with 'Per [mutmut-docs][md]' repeated ~10 times. The bulk (config table, commands, worked example) is efficient, so this sits between the 2 and 3 anchors — noticeably tighter than padding, but with several sections that could be trimmed. | 3 / 5 |
Actionability | Concrete, copy-paste-style commands throughout (install, run, browse/apply/revert loop, CI yaml, worked example) cover the common cases. It falls short of 5 because the PR wrapper uses 'mutmut run --paths-to-mutate' and '--max-children 4' — 2.x-era flags inconsistent with the 3.x config style shown elsewhere ('pytest_add_cli_args_test_selection'), and the prose says to scope via source_paths while the script uses the flag. | 4 / 5 |
Workflow Clarity | Steps 1-7 are clearly sequenced with explicit validation checkpoints: 'confirm the pytest / unittest suite is green before mutating', the apply → test-should-fail → git checkout revert loop, and the worked example's verify-and-rerun. The disk-writing mutant application is a risky batch-style operation and it has explicit feedback loops, so the workflow-clarity cap does not apply. | 5 / 5 |
Progressive Disclosure | references/mutmut-pitfalls.md exists, is exactly one level deep, and is clearly signaled inline ('catalogued in [references/mutmut-pitfalls.md]'), verified against the actual bundle. It is not a 5 because offload is minimal — the mutator catalog and full CI yaml remain inline in a ~210-line body with only one reference file. | 4 / 5 |
Total | 16 / 20 Passed |