Content
88%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 dense, expert-level migration playbook with copy-paste-ready commands, a clearly sequenced workflow with explicit validation gates, and well-signaled external references. Its main weakness is length: the file inlines reference-grade detail that could live in separate files, and repeats its core soundness argument in several places.
Suggestions
Split the 'Clearing coupling the scan won't show' taxonomy and the permanent-interface exception into a separate references file (e.g. COUPLING-CASES.md) and summarize the move-per-kind table in SKILL.md, keeping the body an overview.
Consolidate the ignore_imports-gates-the-skip soundness argument into one place (e.g. step 5) and reference it from step 6, the presentation wave, and the done criteria instead of restating it each time.
Extract the PR-strategy and presentation-wave sections into their own reference files, leaving SKILL.md to point to them, to bring progressive disclosure closer to a clean overview-plus-references structure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Information-dense and assumes Claude's intelligence (no explaining what a facade/serializer/tach is), with nearly every sentence carrying actionable or structural content; held below 5 by overall length and some repetition of the ignore_imports-gates-the-skip soundness argument across step 5, step 6, the presentation wave, and the done criteria. | 4 / 5 |
Actionability | Fully executable guidance — copy-paste-ready commands (hogli product:isolate:scan/move, product:crossings --all --write-baseline), exact file paths (backend/facade/contracts.py, tach.toml, pyproject.toml TODO section), concrete code patterns (pydantic.dataclasses.dataclass, related_name="+", # isolation:permanent-interface), and named worked examples covering common cases. | 5 / 5 |
Workflow Clarity | A clearly sequenced 6-step migration workflow with explicit validation checkpoints (product:lint fails if any chain step is skipped, blocks backend:contract-check while ignore_imports entries remain), error-recovery feedback loops (regenerate-on-conflict instead of hand-resolve), and a final done-criteria checklist — satisfying the batch/destructive validation requirement. | 5 / 5 |
Progressive Disclosure | Good section structure and well-signaled one-level-deep external references (Core docs to load first, the Visual review reference implementation), with no bundle files present; held below 5 because substantial reference-grade material (the coupling-clearing taxonomy, permanent-interface exception, PR-strategy detail) is inlined in one ~570-line file rather than split into separate reference files. | 4 / 5 |
Total | 18 / 20 Passed |