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.
A well-engineered process skill: the workflow is explicitly sequenced with validation checkpoints and error-recovery loops, and tooling guidance is concrete. Its main weaknesses are redundancy — the same guardrails restated across four sections — and references to resource files that are not present in the bundle.
Suggestions
Consolidate the repeated two-hats/behavior-mixing and Mikado rules into one authoritative section (e.g., Guardrails) and reference it from the workflow instead of restating it four times.
Ship the referenced resource files (resources/definition.md, resources/measurement.md, resources/governance.md) or inline their critical content — currently the git one-liners and tool registry they hold are unavailable.
Normalize the References section to consistent relative paths and add brief one-line descriptions for the shared core files, matching the treatment of the resources/ files.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body assumes Claude's competence (no padding with basic refactoring concepts), but the same rules repeat across four sections: "never mix behavior changes" appears in PREPARE (two-hats), Transitions, Guardrail 5, and the canonical workflow, while the Mikado procedure is restated in Scenes, Transitions, the failure table, and the workflow. This is 'mostly efficient but could be tightened' rather than the 'minor instances' of a 4. | 3 / 5 |
Actionability | Concrete specifics are present: "uvx lizard / uvx radon", "jscodeshift / OpenRewrite / ast-grep / comby", "refactor:-typed commits", and explicit artifact paths, plus a directed per-transformation loop. It falls short of a 5 because key executable details (git forensics one-liners, tool registry) are deferred to resource files and no copy-paste command sequence exists for the verification step itself. | 4 / 5 |
Workflow Clarity | The sequence is explicit (PREPARE → ACQUIRE → REASON → ACT → VERIFY → FINALIZE) with a hard validation checkpoint ("Re-run existing tests unchanged") and genuine feedback loops: the Mikado record-revert-recurse loop plus a Failure/Recovery table mapping each failure mode to a recovery. This matches the 'clear sequence with explicit validation steps; feedback loops for error recovery' anchor. | 5 / 5 |
Progressive Disclosure | References are clearly labeled, described, and one level deep (resources/definition.md, resources/measurement.md, resources/governance.md, plus shared core files). However, none of the referenced files exist in the bundle, and the References section mixes path styles with uneven formatting; some inlined process detail duplicates what the resource files would carry — 'good structure... minor organization gaps' rather than fully clean navigation. | 4 / 5 |
Total | 16 / 20 Passed |