Content
61%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.
This is a dense, high-signal internal reference: every line is project-specific invariant knowledge with exact symbols, files, and regression tests. Its weaknesses are structural — the per-run Pi profile section is one unbroken paragraph mixing semantics, validation ordering, and a wall of test names, and no sequenced workflow ties the rules together.
Suggestions
Break the 'Per-Run Pi Profile Pin' section into labeled sub-points (immutability, validation-before-supersede, trust-policy behavior, enforcement, regressions) instead of one paragraph, and move the regression test lists into a compact trailing 'Regressions' block or a reference file.
Add a short worked example of the precedence resolution and the eval candidate spelling (e.g., 'agent,model=pi[,effort=high]') so maintainers have copy-paste-ready syntax rather than prose descriptions.
Sequence the main rules as an ordered decision path (where to add a harness, how a request flows through agent.NewWithOptions, how precedence is resolved, how eval replay is checked) so the invariants double as a workflow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | All content is project-specific with no explanations of concepts Claude already knows, but the second section is a monolithic paragraph that buries core semantics under an inline flood of regression test names and could be substantially tightened. | 3 / 5 |
Actionability | Concrete directives name exact symbols and locations ("Add a harness there, not in an adapter or in eval", "Never re-derive a model or effort flag at a call site", "centralized in `agentcfg.ServedMatchesRequested`") with real file and test paths, though no copy-paste examples of candidate syntax or precedence resolution are given. | 4 / 5 |
Workflow Clarity | The body presents invariants and precedence rules rather than a sequenced process, and no validation checkpoints exist; the rules themselves are unambiguous but there is no workflow structure to attach checkpoints to. | 3 / 5 |
Progressive Disclosure | The body is under 50 lines with two clear sections and one-level-deep references to repo docs (eval.md, global-config.md), but the second section is a single dense bullet and semantics ownership is scattered rather than navigable. | 4 / 5 |
Total | 14 / 20 Passed |