Content
81%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.
An excellent operational playbook: every phase has executable commands, expected results, gotchas, and rollback paths, and the destructive batch operation is properly gated by dry-run and verify steps. Its weakness is redundancy — a duplicated Anti-Patterns section and decorative output transcripts that pad the token budget without adding actionable guidance.
Suggestions
Merge the two 'Anti-Patterns' sections (~lines 175-181 and 229-236) into one — they overlap heavily (autopilot, mapping_rules, restore window) and the duplication wastes context tokens.
Move the multi-line Output Format stderr transcript and celebration-summary box to a reference file, keeping only the one or two lines Claude needs to recognize progress (e.g. 'phase=retype-explicit applied=N'), trimming roughly 20 lines from the body.
Tighten the 'Mental model' paragraph to the decision-relevant facts (94 → 15 canonical types, subtypes to frontmatter, redirects to alias rows, unknowns binned to note) and drop the historical narrative about how the proliferation accreted.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient — non-obvious operational gotchas like 'the job sits queued forever' without --follow on PGLite and 'apply defaults to false' earn their tokens. But it can clearly be tightened: the 'Anti-Patterns' section appears twice (lines ~175 and ~229) with overlapping content, the boxed 'celebration summary' is decorative, and the 'Mental model' paragraph narrates history ('accreted 94 distinct pages.type values over years') beyond what's needed to act. This matches anchor 3 — mostly efficient with some unnecessary content — rather than 4, where only minor trimming would be needed. | 3 / 5 |
Actionability | Fully executable throughout: exact commands with JSON params ('gbrain jobs submit unify-types --follow --params "{\"target_pack\":\"gbrain-base-v2\",\"apply\":true}"'), expected outputs for verification, a copy-paste rollback SQL statement, and concrete failure signals ('stays queued here means no worker is running'). Guidance covers the common cases end-to-end. | 5 / 5 |
Workflow Clarity | A five-phase migration with explicit checkpoints befitting a batch/destructive operation: dry-run preview before apply ('don't proceed... file an issue'), a dedicated Verify phase with expected findings ('pack_upgrade_available → ok', '≤16 distinct types'), a full Rollback section with a 72h restore window, and feedback loops ('A job that stays queued here means no worker is running; resubmit with --follow'). The validation cap for batch operations is satisfied — not a 4 because checkpoints, error recovery, and rollback are all explicit. | 5 / 5 |
Progressive Disclosure | No bundle files exist, so this scores on body structure: well-organized sections with clear headers and a final Reference list of one-level-deep external links. Anchor 4 fits — good structure, mostly well-placed content — but the duplicated Anti-Patterns sections, the multi-line Output Format transcript, and the Contract section's detail are candidates for separate reference files in a ~270-line body, which is the 'minor organization gaps' of anchor 4 rather than the clean split of anchor 5. | 4 / 5 |
Total | 17 / 20 Passed |