Content
42%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 well-structured with sensible use/don't-use, safety, and output-format sections, but it delivers almost no executable guidance: instructions are abstract imperatives, the detail-bearing playbook file it twice points to is missing from the bundle, and the opening paragraph redundantly restates the description. As written, an agent following it would stall at 'open the playbook'.
Suggestions
Either create 'resources/implementation-playbook.md' with the detailed patterns or remove both references to it; a dangling path is worse than no reference.
Make the Instructions concrete: how to spot refactor candidates (e.g., duplication thresholds, long functions, SOLID violations), how to run the test suite, and a validate-fix-retry loop for each refactor step.
Delete the duplicated role paragraph — the frontmatter description already establishes the persona, so those tokens are pure overhead.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is short and sectioned, but it opens by duplicating the frontmatter description verbatim ('You are a code refactoring expert specializing in clean code principles, SOLID design patterns...') and repeats the same playbook pointer in both Instructions and Resources; it could be tightened. | 3 / 5 |
Actionability | The instructions are high-level hints with no concrete guidance: 'Identify high-impact refactor candidates and risks', 'Break work into small, testable steps', 'Validate with tests and targeted regression checks' give no commands, criteria, examples, or specific steps to execute — and the file that would hold the details ('resources/implementation-playbook.md') does not exist. | 2 / 5 |
Workflow Clarity | A rough sequence exists (identify candidates → break into steps → apply → validate), but checkpoints are implicit and vague: 'Validate with tests and targeted regression checks' names no test command or regression procedure, and for codebase-wide cleanup of accumulated debt there is no validate-fix-retry feedback loop. | 3 / 5 |
Progressive Disclosure | Sections are well organized and the single reference is clearly signaled in two places, but scoring against the actual bundle (which is empty) shows the referenced 'resources/implementation-playbook.md' does not exist — a dangling pointer that breaks navigation rather than aiding it. | 3 / 5 |
Total | 11 / 20 Passed |