Content
65%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, disciplined doctrine document: every token carries field-tested rules with concrete mechanisms and named tools, and it trusts the reader's competence. Its weaknesses are structural rather than substantive — it is a principles catalog with no sequenced workflow, and everything lives inline in one file with no progressive disclosure to reference material.
Suggestions
Add a short ordered workflow section (e.g., 1. audit existing gates for vacuous green → 2. place checks per the three-tier topology → 3. self-test each gate by injecting a regression → 4. run `just verify`) so a session repairing a gate system has a sequence with explicit checkpoints.
Split the incident catalog (the three vacuous-green field incidents and the core-innovation tripwire story) into a references/ file, keeping SKILL.md as the rules-plus-signals overview with a clearly linked one-level-deep reference.
Include one portable, copy-paste example of a hook header declaring BLOCKING vs ADVISORY checks and a gate self-test snippet, so the directives generalize beyond the originating frankensqlite/just workspace.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body never explains concepts Claude already knows; every section carries project-specific doctrine ("Probe for a dependency the way the dependency actually presents", "Stale exceptions fail the lint"). Minor tightening opportunities exist — the "Field origin" preamble and repeated restatements of the vacuous-green rule across the intro and bullets — but there is no padding or filler, so it sits above the '3' anchor's "some unnecessary explanation". | 4 / 5 |
Actionability | Concrete, executable directives appear throughout: "just verify: fmt-check + lint + arch-lint + full tests + generated-docs build", "configured fail_on_skipped", "parse build metadata (cargo metadata)", "site-local #[allow(lint, reason = \"...\")]", "a verify script self-tests by injecting a known regression". It stops short of a 5 because several anchors are project-specific (frankensqlite, beads, `verify_<bead>.sh`) with no portable hook or script example to copy. | 4 / 5 |
Workflow Clarity | The content is organized as parallel principles, not a sequenced process — there is no ordered workflow for designing or repairing a gate system (the closest thing is the three-tier commit/push/opt-in placement, which is a topology, not a sequence). Validation doctrine is pervasive, so this is not a '2', but a reader cannot follow numbered steps with checkpoints, capping it at 3. | 3 / 5 |
Progressive Disclosure | The skill is a single 160-line file with no references/, scripts/, or assets/ directories and no pointers to external material; well-organized section headers keep it coherent, but content that would naturally split out (the incident catalog, the exception-file regime, hook examples) is all inlined in SKILL.md. That matches 'some structure ... content that should be separate is inline' rather than the well-split '4'. | 3 / 5 |
Total | 14 / 20 Passed |