Content
67%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 actionable, well-structured operational guide with executable bash for every workflow step and useful opinionated defaults (no cover/TOC, CONTAINER=1, delivery channel caveats). Its main weaknesses are redundancy — the core rule and the cover/TOC rationale are each repeated two to three times — plus placeholder conformance sections, an unverified `--raw` flag, and a mandated emoji-sanitization step that is never implemented.
Suggestions
State the "brain page is the source of truth" rule once and consolidate the three separate cover/TOC explanations (Invocation comment, Common patterns, Defaults section) into a single Defaults section to cut roughly a fifth of the body.
Resolve the `gbrain get "$SLUG" --raw` uncertainty — verify the actual flag and bake it into the snippet — and add the missing emoji-sanitization command, since both the description and the Anti-Patterns section require it.
Add a post-render checkpoint (e.g. `[ -f "$OUT" ] || { echo "Render failed" >&2; exit 1; }`) before delivery, and either link the conventions files (brain-first.md, _brain-filing-rules.md) from the sections that use them or drop them from the Contract section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient, code-heavy, and free of textbook explanation, but it carries real padding: the "brain page is the source of truth" rule is stated twice (opening blockquote and "The rule"), the no-cover/no-TOC rationale appears three times (Invocation comments, Common patterns, and the dedicated "Defaults" section), and the "Contract"/"Output Format" sections are explicitly conformance-test placeholders. Version-sensitive details ("a future v0.26+", "for v0.25.1 gstack is a soft prereq") also sit inline rather than in a deprecated/old-patterns section. This is tighter than score 2's noticeably padded profile but not the lean score-4 body, since roughly a fifth of the file is duplicate or filler content. | 3 / 5 |
Actionability | The guidance is largely copy-paste executable: the binary existence check (`[ -x "$P" ] || ... exit 1`), the page existence check (`gbrain get "$SLUG" || ... exit 1`), the fallback between repo file and API fetch, the sed frontmatter strip, and the render invocation with `CONTAINER=1`, plus channel-specific delivery instructions. Two gaps keep it from score 5: `gbrain get "$SLUG" --raw # whatever flag exposes raw body` is an admitted guess rather than a verified command, and emoji sanitization is mandated (workflow step 2 rationale, description, anti-patterns) yet no command implements it. | 4 / 5 |
Workflow Clarity | The RESOLVE → STRIP → RENDER → DELIVER workflow is explicit and carries real precondition checkpoints (verify make-pdf is executable; confirm the brain page exists before doing anything). It is not score 5 because there is no post-render checkpoint — nothing verifies "$OUT" was created or reports render failure before delivery — and no feedback loop for error recovery; it stays above score 3 because the risky preconditions are validated rather than merely listed. | 4 / 5 |
Progressive Disclosure | The single-file body is well organized into scannable sections (Workflow, Invocation, Common patterns, Defaults, Fonts, Delivery, Anti-Patterns) with no wall of text, and the conventions reference is one level deep and clearly signaled. It falls short of score 5 because several referenced paths — `../conventions/quality.md`, `skills/book-mirror/SKILL.md`, `test/skills-conformance.test.ts` — point outside the skill and cannot be resolved from the bundle, and the Contract section lists conventions (`brain-first.md`, `_brain-filing-rules.md`) that are never linked from the guidance itself. | 4 / 5 |
Total | 15 / 20 Passed |