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.
The body is an exceptionally actionable, well-sequenced operational runbook with genuine validation and failure handling for a destructive, multi-session operation. Its weaknesses are structural: the monolithic 370-line file inlines reference-grade material (fallback script, compatibility file list, worker cleanup) that belongs in one-level-deep reference files, and the cross-section repetition of the same safety rules inflates the token cost.
Suggestions
Move the emergency fallback script and the explicit legacy/global compatibility file list into reference files (e.g. references/emergency-fallback.md and references/legacy-compat.md) linked from short, clearly signaled sections, keeping SKILL.md as a lean overview of the four-phase flow.
Consolidate the lock/ownership and fail-closed rules, which are restated in "What It Does", "Cancellation Flow", "Authorized Global Pass", and "MCP Worker Cleanup", into a single stated-once contract section.
Extract the per-mode handling details (Team/Ralph linkage, Self-Improve worktree rules, MCP worker heartbeat handling) into a per-mode reference table or file so the main flow reads as one page.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every token is domain-specific operational detail rather than concepts Claude already knows, but the same rules (lock/ownership enforcement, Team-first ordering, global-pass gating) are restated across "What It Does", "Cancellation Flow", "Preserved State", and "MCP Worker Cleanup" — noticeably tighter than ideal, though the repetition is arguably defensive emphasis for a destructive operation. Not 2 because there is no filler or explanation of known concepts; not 4 because the cross-section repetition could be consolidated. | 3 / 5 |
Actionability | The body provides copy-paste-ready artifacts for every common case: the exact `ToolSearch` deferred-tool query, a complete bash argument parser, the exact `state_write`/`state_clear` call forms with parameters, the `cleanup-orphans.mjs` invocation with `--dry-run`, and a fully executable emergency fallback script (with its placeholders explicitly flagged). | 5 / 5 |
Workflow Clarity | The four-phase sequence (Parse Arguments → Detect Active Modes → Cancel Each Session → Authorized Global Pass) has explicit validation checkpoints: fail-closed identity resolution, `state_get_status` before each mode cleanup, the per-mode dependency order, and explicit failure handling (retain state, report scope and reason, block the global pass) with retry-in-same-scope guidance — fully satisfying the destructive/batch-operation feedback-loop requirement. | 5 / 5 |
Progressive Disclosure | There are no reference files at all: the ~90-line compatibility file list, the emergency fallback script, and the MCP worker cleanup details are all inlined in a ~370-line body. Section headers are clear and there is no nested-reference problem, so this is not a 2, but material that clearly belongs in separate reference files is inline with no external pointers, capping it at 3. | 3 / 5 |
Total | 16 / 20 Passed |