Content
63%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 exceptionally actionable — copy-paste run commands, a complete operator hook script, explicit env-var contracts, and rigorous SKIP/FAIL validation discipline — but it is a 778-line monolith that inlines incident narratives, dated verification histories, session IDs, and a per-cell catalog that belong in the already-referenced coverage.md and LESSONS.md. Halving the file by cutting war stories to one-line lessons and moving the cell catalog out would lose nothing operational while roughly halving the context cost.
Suggestions
Move incident narratives and verification histories (dated episodes, session IDs such as 58ce3a58-8d04-40ac-99e4-c44eaa5d7b06, 'Verified PASS 3/3 runs after the tunnel-seat fix (2026-08-06)') into resources/LESSONS.md or a dedicated evidence file, leaving only the one-line lesson inline — this targets conciseness, the lowest-scoring dimension.
Replace the ~400-line per-cell resource catalog with a compact table (cell → purpose → tier) in SKILL.md and push the per-cell detail into resources/coverage.md, which already exists for exactly that content — this improves progressive_disclosure alongside conciseness.
Consolidate time-sensitive facts (v0.117.0, 2026-08-06 dates, PR/session references) into a changelog or old-patterns section in a reference file so the main body stays evergreen and does not penalize clarity as facts age.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body runs ~778 lines and is padded with incident narratives and verification transcripts: "Cost a staging gate run on 2026-08-28", "left the runner down for about seven minutes mid-gate on 2026-09-10", "session 58ce3a58-8d04-40ac-99e4-c44eaa5d7b06", "Verified PASS 3/3 runs after the tunnel-seat fix (2026-08-06)", plus trial-by-trial model-behavior transcripts and open editorial questions ("Worth a call: whether the guidance text needs to be more directive"). Not 1 because none of it explains concepts Claude already knows — it is all non-obvious project knowledge; not 3 because the volume of narrative padding goes well beyond "some unnecessary explanation", and dated/time-sensitive facts are scattered throughout rather than confined to a changelog or old-patterns section. | 2 / 5 |
Actionability | Quotes: "uv run resources/qa_product.py --all --custom-slug <vault-slug> --custom-name \"<display-name>\" --require-store" (plus single-cell and single-journey variants), the complete executable /tmp/replace-runner.sh hook script with kill/start/health-wait, "uv run resources/session_control.py --cells all --harness pi_core --sandbox local", and enumerated AGENTA_QA_* env vars with defaults ("--burst-size (default 16)"). Copy-paste-ready commands cover the common cases: full run, one cell, one journey, continuity, session control, and commit approval. | 5 / 5 |
Workflow Clarity | Quotes: "EXPORT the three variables, do not just set them", "Any FAIL blocks the release until triaged", "the release is not green until each of those has a recorded result of its own", "Run dead LAST", and explicit SKIP-vs-FAIL semantics ("A SKIPped integration test in a security- or concurrency-bearing area is a FAILURE in your summary line"). The run sequence is clear with strong validation checkpoints and error-recovery guidance throughout. Not 5 because the full release-run ordering across the multiple drivers (qa_product.py, session_control.py, matrix cells, qa_commit_approval.py) is distributed across sections and deferred to coverage.md rather than given as one consolidated checklist; not 3 because checkpoints are explicit and pervasive, and destructive operations (kill hooks) carry explicit validation. | 4 / 5 |
Progressive Disclosure | A "Resources (read on demand)" section signals one-level-deep references with purpose descriptions ("resources/coverage.md — the cells (harness × sandbox × auth), the journeys... a table of what each cell needs beyond the three env vars"), and "Full runbook and ordering: resources/coverage.md" points elsewhere for detail. However, 400+ lines of per-cell documentation, incident history, and evidence transcripts that belong in coverage.md/LESSONS.md are inlined in SKILL.md itself. Not 4 because a large fraction of the content is inappropriately placed in the overview file rather than having "minor organization gaps"; not 2 because structure is present and references are clearly signaled, not buried. Note also that the referenced resources/ files are not present in this bundle, so the references could not be verified against actual files. | 3 / 5 |
Total | 14 / 20 Passed |