Content
46%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 an exhaustively concrete but monolithic invariant dump: every rule is anchored to real files, functions, and regression tests, yet the 60KB single-file wall with zero bundle references makes it expensive to load and hard to navigate. Splitting per-subsystem reference files and tightening the run-on sentences would address both weakest dimensions.
Suggestions
Split each bold subsystem section (sessions, recorded decisions, timeouts, Test contract, review carry, approval overrides) into its own file under references/ and keep SKILL.md as a one-page index with one-line summaries — this fixes the missing progressive disclosure.
Break the 100+ word run-on sentences (especially the timeout and fix-response sections) into short rule statements; roughly half the current token load is clause nesting that could be flattened without losing information.
Move the exhaustive regression-test name lists into the per-topic reference files and keep only the primary test per invariant inline, so the always-loaded overview carries the rules rather than the full test inventory.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 60KB body is a wall of mammoth run-on sentences with nested parentheticals (e.g. the timeout section chaining baseline-freeze, still-working-cap, and #1109-case rules into a single sentence), which could be cut or split drastically. It is not 1 because it never explains concepts Claude already knows — every line is repo-specific invariant — but the density-per-token is poor and much phrasing is redundant. | 2 / 5 |
Actionability | Guidance is concrete and specific throughout: exact file paths ("internal/pipeline/sessions.go"), function names ("splitFixResponse", "mergeOutstandingFindingsJSON"), config keys ("review_agent_working_timeout"), explicit directives ("Do not raise the shipped 30m default"), and named regression tests. It is not 5 because the prose describes invariants rather than giving copy-paste-ready coverage of the common cases an editor would execute. | 4 / 5 |
Workflow Clarity | The body is organized into clearly labeled subsystem sections, each stating coherent fail-safe rules ("a failed fixer resume drops the identity and re-runs the same turn, never skipping the turn"). However, there are no multi-step sequences or validation checkpoints anywhere — it is descriptive invariant prose, not a workflow — so it cannot reach 4. | 3 / 5 |
Progressive Disclosure | No references/, scripts/, or assets/ exist; the entire ~12-subsystem corpus (sessions, decisions, timeouts, Test contract, review carry, etc.) is inlined in one 60KB monolith where each section clearly belongs in its own reference file. The bold section headers provide some structure, keeping it above 1, but the total absence of any file split matches the anchor for content that clearly belongs in separate files being inlined. | 2 / 5 |
Total | 11 / 20 Passed |