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 audit procedure with strong validation gates and real, well-integrated reference files. Its main costs are token weight in SKILL.md itself — long environment-specific sections that belong in references — which pulls down conciseness and progressive disclosure.
Suggestions
Move the 'Tracked configuration coverage' triage detail and the never-track table into a references/ file (e.g. references/tracked-config-coverage.md), keeping only the `just audit-ignored-config` command and the Critical-severity rule inline in SKILL.md.
Trim the procedural-skill exception paragraph in 'Plugins and skills' by moving the named-skill examples (`using-git-worktrees`, `backlog-batch-delivery`, `executing-plans`) into a reference or short list, keeping the general rule inline.
Compress the 'Control-plane note' to the protected-path list and the single proposal workflow pointer, moving the `ness policy` candidate/proposal detail into a reference file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is information-dense with no concept explanations Claude already knows, but several sections could be tightened or relocated: the ~75-line 'Tracked configuration coverage' triage with its table, the 'Control-plane note' path inventory, and long exception parentheticals like "(for example `using-git-worktrees` pointing at `/git:worktree`) or sits inside a workflow the user started explicitly (`backlog-batch-delivery` steps, `executing-plans` finishing with `branch-finish`)". This is more than the 'minor instances' of the 4 anchor, but well short of the padding of the 2 anchor. | 3 / 5 |
Actionability | Guidance is copy-paste executable throughout: `python3 ~/scripts/harness-sessions.py <slugs> --since <N> --json`, `just audit-ignored-config .omp .pi`, `git log --oneline -- <hook script>`, `codex debug prompt-input`, a concrete YAML snippet for `agents/openai.yaml`, a worked example ("$optimize-harness claude hooks since:14"), and a complete output template. Common cases are covered by specific commands, matching the 5 anchor. | 5 / 5 |
Workflow Clarity | The 'Execution shape' gives a clearly numbered sequence ('Run one deterministic scan first', fan out audits capped at 3 concurrent, structural transcript privacy boundary) with explicit validation gates ("A finding with no evidence is dropped, not softened"; "Never render `unknown/not observed` as `unused`"), error-recovery paths for invalid tokens ("stop and print the two valid token sets above. Do not guess") and absent harnesses ("reported as `not installed / not configured` and skipped"), plus a read-only guardrail ("Do not mutate config during the audit"). Sequence, checkpoints, and a dimension checklist are all present, satisfying the 5 anchor rather than the 4. | 5 / 5 |
Progressive Disclosure | All three bundle references exist and are clearly signaled with when-to-read guidance (`references/harness-map.md`, `references/session-usage-evidence.md`, `references/agent-harness-portability.md`), and they are one level deep within the bundle. However, the long inline 'Tracked configuration coverage' section and the portability mapping rules (which duplicate `references/agent-harness-portability.md`) are content that could live in reference files, and reference files point onward to out-of-bundle docs (`docs/agent-session-transcripts.md`) — minor organization gaps that fit the 4 anchor rather than the clean split of the 5 anchor. | 4 / 5 |
Total | 17 / 20 Passed |