Content
75%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.
A well-organized operational contract: executable commands, exact env vars and paths, a guarded rollback sequence with verification, and clear one-level-deep delegation to docs/gateway.md. Weaknesses are minor: an inline review date, a convoluted reserved-flag paragraph, and a missing concrete invocation for the rollback script and duplicate-poller diagnosis.
Suggestions
Move the 2026-08-12 `--kind` review date (and other migration-state notes) into an 'old patterns / deprecated' section so time-sensitive details don't age the main guidance.
Show the exact guarded invocation of `scripts/gateway-cutover-rollback.sh` (with the old pane ID argument) rather than describing it, and give a concrete step for locating a duplicate Telegram poller on a 409.
Consider moving the recurring-incident producer contract and fallback batching rules into a reference file (e.g., references/incident-contract.md), keeping SKILL.md as a lean overview with clearly signaled one-level-deep pointers.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with project-specific policy Claude cannot know (latch reconstruction, three-slot limit, fallback batch rules, single-owner doctrine) — nearly every token earns its place. Not 5 because a time-sensitive date is inline outside any 'old patterns' section ("Review making `--kind` required on 2026-08-12") and the reserved-but-unimplemented `--data`/`--ref` paragraph is slightly tangled; not 3 because there is no padding or explanation of concepts Claude already knows. | 4 / 5 |
Actionability | Concrete, copy-paste-ready commands are given: `joelclaw notify send "The deploy failed..."`, the `--context '{...}'` JSON example, `joelclaw messages trace <flowId>`, plus exact env vars (`FALLBACK_CHANNEL=telegram`, `GATEWAY_TRANSPORT_SLIM_DOWN=1`) and file paths. Not 5 because the rollback script's invocation syntax is never shown ("invoke the script with the old pane ID" without the exact command) and how to locate a duplicate Telegram poller after a 409 is unspecified. | 4 / 5 |
Workflow Clarity | The destructive rollback flow has an explicit guarded sequence with verification checkpoints ("verify the backup, stop the driver, close the gateway pane, verify the stable label is absent, then invoke the script"), and error recovery is addressed (a 409 means a forbidden second poller — find and stop it; do not mask it). Not 5 because the checkpoints are prose rather than a numbered validate/recover loop, and the duplicate-poller diagnosis step has no concrete procedure; not 3 because validation for the risky rollback operation is explicitly present, avoiding the destructive-operation cap. | 4 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent), and the body appropriately delegates runtime operations and rollback detail one level deep with a clearly signaled pointer: "Load `docs/gateway.md` or the `gateway` skill for runtime operations". Sections are well-organized and navigable. Not 5 because specialized policy (the recurring-incident producer contract and fallback batching rules) is fully inlined in SKILL.md where a reference file would keep the overview leaner. | 4 / 5 |
Total | 16 / 20 Passed |