Content
45%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 delivers a genuinely useful staged upgrade methodology with concrete npm/yarn commands, per-step test checkpoints, and a rollback plan. However, it is padded with concepts Claude already knows, contains fabricated or non-executable tool examples, and its progressive disclosure is broken: it cites seven-plus bundle files that do not exist while inlining all of that content anyway.
Suggestions
Fix progressive disclosure first: either create the advertised `references/`, `assets/`, and `scripts/` files and move the inline semver guide, compatibility matrix, testing strategy, and checklist into them, or delete the Resources section and the `resources/implementation-playbook.md` pointer — also reconciling the inconsistent `resources/` vs `references/` path prefix.
Remove or verify fabricated commands: replace `npx react-codeshift` with the real React codemod workflow, drop or correct `npx changelog-parser`, strip `//` comments from the renovate JSON, and implement or delete the `checkCompatibility` stub.
Cut token spend on known concepts: delete the Semantic Versioning Review section (or compress it to the ^/~ cheat line), and trim the generic Best Practices/Common Pitfalls lists to only non-obvious advice like lock-file and peer-dependency gotchas.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body spends significant tokens re-teaching what Claude already knows: a "Semantic Versioning Review" explaining MAJOR.MINOR.PATCH and ^/~ semantics, generic "Best Practices" and "Common Pitfalls" lists, and repeated bare `npm run test` blocks. Multiple padded sections match the "noticeably verbose; several unnecessary explanations" anchor; it is not a 3 because the padding spans many sections rather than being minor. | 2 / 5 |
Actionability | Much of the guidance is executable (`npm outdated`, `npx npm-check-updates -u`, Dependabot YAML, rollback script), but there are real gaps and fabrications: `checkCompatibility()` is an empty stub, the renovate config contains `//` comments making it invalid JSON, `npx changelog-parser react 16.0.0 17.0.0` and `npx react-codeshift` are non-existent tools/usages, and `rollback.sh` is fenced as JavaScript. This fits the anchor for concrete guidance that is incomplete with pseudocode elements rather than the mostly-executable anchor of 4. | 3 / 5 |
Workflow Clarity | The Staged Upgrade Strategy gives a clear sequence — Planning (identify versions, read changelogs) → Incremental Updates with an explicit "Test" checkpoint after each upgrade → Validation — plus a rollback script with a failure branch and a pre/during/post checklist. It misses a 5 because the workflow is fragmented across topic sections instead of one coherent flow, and the Phase 3 peer-dependency test is only an empty comment. | 4 / 5 |
Progressive Disclosure | The Resources section lists `references/semver.md`, `assets/upgrade-checklist.md`, `scripts/audit-dependencies.sh`, and four other bundle files, but none of these files (nor the `resources/implementation-playbook.md` cited in Instructions) exist on disk — every reference is dangling. Meanwhile the material those files would hold (semver guide, compatibility matrix, testing strategy, upgrade checklist) is duplicated inline in a ~425-line body, matching the anchor for content that clearly belongs in separate files being inlined with broken navigation. | 2 / 5 |
Total | 11 / 20 Passed |