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.
A dense, highly actionable operational reference: every debug recipe is symptom-keyed with concrete commands and validation gates, and structure is easy to navigate. Weaknesses are minor — some time-sensitive dates sit outside the retirement sections, the retirement note is stated twice, and recipes rarely close the loop with an explicit recovery path after a failed check.
Suggestions
Consolidate the top 'Memory retirement (2026-07-17)' blockquote into the 'Retired and parked surfaces' section to remove the duplicated retirement story.
Move the inline date annotations ('Since the 2026-07-17 fix', 'taste bench (2026-07-17)') into the retirement/deprecated sections so time-sensitive detail lives in one place.
Add a one-line fix-and-retry step to recipes that currently end at verification (e.g., what to do when the delivery canary exits non-zero or the journal row is missing).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Prose is telegraphic and fact-dense (paths, event names, commands) with zero padding or explanation of known concepts, but inline dates ('Since the 2026-07-17 fix', 'taste bench (2026-07-17)') sit outside the retirement/deprecated sections and the top blockquote duplicates the 'Retired and parked surfaces' section, leaving minor trims. Anchor 4 fits better than 5. | 4 / 5 |
Actionability | Commands are copy-paste ready and cover the common cases: 'jq --arg slug "<slug>" '.sent[] | select(.slug == $slug) | {slug, outcome}' ~/.joelclaw/observer-neat-memories.json', 'bun scripts/backfill-session-index.ts' with dry-run then --apply, 'bun scripts/messaging-visible-delivery-canary.ts' with an exit-0 success criterion, plus concrete emoji-to-outcome mappings. Fully executable guidance matching anchor 5. | 5 / 5 |
Workflow Clarity | Recipes are ordered symptom-to-fix with validation gates on risky operations (--dry-run promotion, dry-run backfill, 200-check before sharing, exit-0 canary) and a forked decision path ('Chain alive → ...; Chain dead → ...'). However, most recipes stop at verification without an explicit fix-and-retry loop if the check fails, matching anchor 4 rather than 5. | 4 / 5 |
Progressive Disclosure | No bundle files exist, so this is scored on body structure: clear section headers (location table, debug recipes, usage, retired surfaces, doctor) with one-level-deep external pointers clearly signaled ('read it before deep debugging'). The location table and behavior-card detail could arguably live in separate reference files, so anchor 4's 'minor organization gaps' fits better than 5. | 4 / 5 |
Total | 17 / 20 Passed |