Content
92%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 audit workflow with excellent progressive disclosure: every step carries executable commands, validation is built in (refutation, verdicts, a validator script), and detail is pushed to real one-level-deep references. The only weakness is length — the body could shed its worked-verdict examples and platform-change dates to references or a deprecated section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious domain specifics (trigger/trust table, the December 2025 pull_request_target default-branch change, fingerprint and ext-key formats) and never explains concepts Claude already knows. It is nonetheless long (~320 lines), carries time-sensitive dates outside any 'old patterns' section, and inlines worked-verdict examples that could live in worked-examples.md — fitting the 4 anchor ('efficient; minor instances of over-explanation that could be trimmed') rather than 5's 'every token earns its place'. | 4 / 5 |
Actionability | Guidance is fully executable throughout: exact commands ("zizmor --offline --format=json .", "actionlint -format '{{json .}}'", "node references/validate-findings.mjs findings.json"), concrete rg/grep patterns, per-trigger trust tables, a verdict table with named YAML examples, fingerprint formats with examples, and a copy-paste report template. Matches the 5 anchor; nothing is pseudocode or hand-wavy. | 5 / 5 |
Workflow Clarity | Six explicitly sequenced steps (Inventory → Run tools → Trigger/holdings analysis → Checks → Platform facts → Verify/record) with real validation checkpoints: a mandatory refutation step, a validator script run before reporting, and a re-run rule ('a rejected record stays rejected unless the line in ruled_out_by.location changed'). The feedback loop (candidate → refute → verdict → validate → write) matches the 5 anchor; a 4 would have missing checkpoints, which it does not. | 5 / 5 |
Progressive Disclosure | The body is a genuine overview that delegates detail to ten real, one-level-deep reference files (checks.md, ai-agents-in-ci.md, gitlab-circleci.md, verification.md, findings-format.md, severity-calibration.md, worked-examples.md, validate-findings.mjs, to-sarif.mjs, findings.schema.json — all verified present), each linked at its point of use with a stated purpose. Navigation is easy and content is appropriately split (~27KB body vs ~125KB references), matching the 5 anchor. | 5 / 5 |
Total | 19 / 20 Passed |