Content
86%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 tight, project-specific diagnostic runbook that respects the token budget and encodes real operational judgment (ownership preservation, evidence discipline, secret hygiene). Its main gap is that the executable diagnostic surface is delegated to the CLI's --help output rather than surfaced in the skill itself.
Suggestions
Surface one or two of the most common diagnostic commands (beyond the --help pointer) inline, e.g. the status and event-inspection invocations used in the typical triage, so the first probe can be executed without an extra discovery step.
Make the implicit sequence explicit — renumber the paragraphs as a short ordered diagnostic checklist (identify → place → trace → isolate → verify/report) so the workflow order and the verify step stand out.
Add a brief feedback-loop line for the trace step (e.g. what to do when the first correlation id dead-ends: advance to the next hop in the path rather than stopping), matching the 'do not stop the whole task' guidance with a concrete recovery action.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~15-line body is lean prose with zero padding: no concepts Claude already knows are explained, and every sentence adds project-specific guidance ("Queue age alone does not prove a hung agent", "A successful queue submission is not proof of delivery"). | 5 / 5 |
Actionability | One concrete command is given ("Use `joelclaw gateway --help` for supported status, event, and diagnostic commands") along with specific comparison artifacts ("timestamps, correlation ids, progress, and configured timeouts"), but the actual diagnostic commands are deferred to --help rather than enumerated, leaving minor gaps. | 4 / 5 |
Workflow Clarity | A clear diagnostic sequence runs through the paragraphs (find the failing id → read entrypoint/config/runbook → resolve service placement → trace the path → follow the first relevant failure → "Verify the affected behavior and report the exact observation"), with a verification checkpoint present, but the sequence is implicit in prose rather than an explicit ordered list and there is no defined error-recovery loop. | 4 / 5 |
Progressive Disclosure | The skill is well under 50 lines with no external references needed, and the short paragraphs are logically ordered under a single heading, so the simple-skill exception applies; nothing that belongs in a separate file is inlined. | 5 / 5 |
Total | 18 / 20 Passed |