Content
82%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 exemplary operational runbook: every command is concrete and executable, environment-specific facts (IPs, ports, paths, bucket names) are recorded precisely, and destructive operations carry explicit authorization and redaction rules. The Operating Sequence includes real verification checkpoints including a workload-level smoke test. Remaining weaknesses are minor: a few duplicated facts across sections and no explicit failure-handling branch in the main sequence.
Suggestions
Deduplicate repeated facts — state 'Garage does not support anonymous S3 access; 403 from / is expected' once (Gotchas) and reference it from Health Checks, and list the installer path once (Canonical Sources) to tighten conciseness toward a 5.
Add a short failure branch to the Operating Sequence (e.g. 'If reachability or the smoke fails: check Gotchas, back off SSH before retrying, re-verify with redaction-safe checks before changing state') to complete the validation feedback loop.
Consider moving the health-check command catalog into a references/ file, keeping only the two canonical checks inline, to improve progressive disclosure now that the single file has grown past 200 lines.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with facts Claude cannot know (tailnet IP, ports 39100/39000/29990, bucket names, NAS paths, SSH-brittleness rules) and explains no general concepts — every section is operational. It falls short of 5 only through minor duplication: the installer path appears twice (Current Topology and Canonical Sources), and 'Garage does not support anonymous S3 access; 403 AccessDenied' is stated verbatim in both Health Checks and Gotchas. This fits 'Efficient; minor instances of over-explanation that could be trimmed' (4); it is clearly above 3 because there is no padded explanation, only repetition of already-earned facts. | 4 / 5 |
Actionability | Guidance is fully executable and copy-paste ready: the read-only SSH probe (`ssh -o BatchMode=yes -o ConnectTimeout=8 joel@three-body 'uptime; pwd'`), network health checks (`nc -vz -w 5 100.67.156.41 39100`), redaction-safe env checks with exact awk patterns, `sudo docker compose ps/logs` commands, the complete Convex env shape with concrete values, and the smoke script invocation `./smoke-self-hosted-convex.sh`. This matches the 5 anchor ('Fully executable; copy-paste ready code or commands; specific examples cover the common cases') and is above 4 because the commands cover the common health-check, env-validation, and smoke-test cases comprehensively rather than with minor gaps. | 5 / 5 |
Workflow Clarity | The 'Operating Sequence' is a clear numbered 7-step flow with explicit verification checkpoints (verify reachability on 39100, validate the redacted env shape, confirm the runtime env endpoint, run the Convex smoke, verify the export ZIP contains 'custom-garage' and the endpoint), and risky operations are guarded ('Do not delete buckets or objects without explicit authorization and a backup/recovery note', 'Inspect first. Summarize risk before changing service state'). It is not a 5 because the sequence lacks an explicit failure-feedback loop — no instruction for what to do when a checkpoint fails — though partial recovery guidance exists elsewhere ('Back off after kex_exchange_identification...', 'If sources disagree, prefer the brain project note, then verify live state'), so it sits at 'Clear sequence with most checkpoints present; minor validation gaps' (4) rather than 3, which would require missing checkpoints or absent validation for destructive operations. | 4 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent), so this is a single-file skill; scoring reflects the actual structure. Section organization is strong and navigable (When To Use, Current Topology, Canonical Sources, Safety, NAS Access Rules, Health Checks, Buckets, Env Shape, Operating Sequence, Gotchas), and external pointers (brain project note, compose file, redacted env) are one level deep and clearly signaled in a dedicated Canonical Sources section with a precedence rule. It is not a 5 because the under-50-lines exception does not apply (~210 lines) and some content — notably the multi-command health-check catalog and the secret-redaction listings — is inline reference material that could be split into a references file, fitting 'Good structure; most content is appropriately placed; minor organization gaps' (4) rather than 3, since the inline content is operational essentials rather than a misfiled API dump. | 4 / 5 |
Total | 17 / 20 Passed |