Content
77%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.
Highly actionable and exceptionally well-sequenced content, with concrete tool calls, explicit validation gates for a destructive operation, and per-error recovery guidance — among the clearest safety workflows for refactoring. Its weaknesses are repetition of the repo-binding rule and the absence of any progressive disclosure: edge-case detail (error table, token lifecycle, semantic-layer internals) that belongs in a reference file is inlined in SKILL.md.
Suggestions
Move the 17-row rename error-recovery table and the plan_token lifecycle details (expiry, eviction at 16 plans/64 MiB, read-only mode) into a references/RENAME-ERRORS.md file, linked one level deep from the rename section, keeping only the 3-4 most common error codes inline.
State the repo-binding rule once in 'Bind the repository first' and reference it from the checklists with a short '- [ ] Bind repo (see above)' item instead of restating the full guidance in every checklist and the risk table.
Trim the semantic-layer paragraph ('Rename uses the indexed graph...') to the operationally relevant facts (fail-closed behavior, no regex fallback, coverage scope), dropping explanatory prose about providers and declaration families that a caller does not act on.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is operationally dense and explains no basic concepts, but repo-binding guidance is restated in roughly six places (intro, workflow, every checklist, risk table, example), and roughly 100 lines cover rare edge cases (plan eviction at 16 plans/64 MiB, duplicate_file/missing_snapshot) that could be tightened or offloaded. Not 4: the repetition and edge-case depth go beyond minor trim instances; not 2: nearly everything is non-obvious, tool-specific fact rather than padding. | 3 / 5 |
Actionability | Calls are copy-paste ready with exact parameters and expected outputs ("rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true})"), plus a concrete cypher query and a full worked example. Not 4: specific examples cover the common rename case end-to-end including apply and verification. | 5 / 5 |
Workflow Clarity | A numbered workflow with per-task checklists, explicit validation gates (preview with dry_run, confirm bound repository, apply only with plan_token, detect_changes, run tests), and a 17-row error-recovery table with per-code next steps. Feedback loops for the destructive write operation are explicit and thorough. Not 4: checkpoints and recovery paths are explicit, not merely present. | 5 / 5 |
Progressive Disclosure | The file is well-sectioned (When to Use, Workflow, Checklists, Tools, Risk Rules, Example), but there are no bundle files at all — content that clearly belongs in a one-level-deep reference (the full error-code recovery table, rename semantic-internals, token lifecycle and read-only behavior) is inlined. Not 4: no references exist and ~100 lines of edge-case API detail sit in the main file; not 2: structure is strong, not minimal. | 3 / 5 |
Total | 16 / 20 Passed |