Content
81%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 highly actionable, well-sequenced workflow document: every step is executable, validation gates precede every batch mutation, and failure handling is thorough. The main weakness is redundancy — the same failure codes and output contracts are restated across Outputs/Contract and When it fails/Failure modes/Anti-Patterns, with inline version trivia adding date-sensitive tokens that would sit better in a single consolidated section or reference file.
Suggestions
Merge the "When it failures" / "Failure modes" overlap: PACK_READONLY, STILL_REFERENCED, and LOCK_BUSY handling currently appears in both sections (plus a third mention of the fork-first rule in Anti-Patterns) — consolidate into one error-code table with a single line of remediation each.
Deduplicate the "Outputs" section against the Contract's Inputs/Outputs bullets, which repeat the same pack-file, audit-row, and backfill content verbatim — keep one canonical location and cross-reference it.
Move version-specific notes ("added in v0.40.6.0", "pre-v0.40.6 brains silently ignored custom expert-routed types", the cross-process invalidation gap closure) into a short 'Version notes / old patterns' section or the linked docs so the main workflow stays date-free.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient — every command and error code carries real operational information and no basic concepts are explained — but there is systematic duplication that could be tightened: the "Outputs" section and the Contract's Outputs bullet are near-verbatim, and "When it fails", "Failure modes", and "Anti-Patterns" each restate PACK_READONLY/STILL_REFERENCED/LOCK_BUSY handling across three sections. Inline time-sensitive version trivia ("v0.40.6.0", "pre-v0.40.6 brains silently ignored") is not confined to a deprecated/old-patterns section, which the guidelines penalize. Not a 4 because the redundancy spans multiple full sections rather than minor trimmable spots; not a 2 because nothing is concept over-explanation or padding. | 3 / 5 |
Actionability | Fully executable throughout: copy-paste-ready commands with real flags for every phase (`gbrain schema active --json`, `fork gbrain-base mine`, `add-type researcher --primitive entity --prefix people/researchers/ --extractable --expert`, `lint --with-db`, `sync --apply`), a concrete JSONL batch example, expected output shapes (would_apply counts, sample slugs), and an enumerated error-code list. Matches the anchor-5 standard of covering the common cases with runnable commands. | 5 / 5 |
Workflow Clarity | The 7-phase sequence (Brain → Assess → Propose → Apply → Sync → Verify → Commit) has explicit validation checkpoints exactly where the batch/destructive risk lives: lint gate before mutation, mandatory dry-run before `sync --apply`, and a Verify phase (coverage ≥95% + `whoknows` spot-check). Error recovery is a real feedback loop (retry once on commit_lock_busy, stop and ask on integrate_conflict, never bypass lint). This is the anchor-5 pattern, not 4, because validation is an explicit workflow step rather than an implied one. | 5 / 5 |
Progressive Disclosure | Good structure: clear section headers, one-level-deep references clearly signaled in the Convention blockquotes (`../conventions/brain-first.md`, `../conventions/schema-evolution.md`, `../conventions/agent-operator-protocol.md`), and external docs appropriately linked under Tutorial + vision. No bundle files exist in this skill directory, and nothing is nested two-plus levels. Not a 5 because of minor gaps: the path for schema-evolution.md is inconsistent (`conventions/schema-evolution.md` in the Convention blockquote vs `skills/conventions/schema-evolution.md` in Anti-Patterns), and the ~50-line Output Format JSON block plus the dense git-outcome prose are candidates for a split-out reference file. Not a 3 because references are well signaled and content is genuinely sectioned rather than a wall of text. | 4 / 5 |
Total | 17 / 20 Passed |