AGENTS.md · git:20261115.e9a4859 · 2026-11-15 · sha256 b4f503bce1777507
AGENTS.md git:20261115.e9a4859A
Immutable. This exact content never changes and is served at /api/v1/blob/b4f503bce1777507.
# Super Review
Super Review is a skill family, not an agent runtime. Reviewing a user's source
is strictly read-only; maintaining this repository permits the requested edits,
builds, and tests. Never confuse those scopes.
## Instruction ownership
- **Super Review (`skills/super-review`):** shared judgment and authority live
in `references/review-contract.md`, domain decisions in `references/lenses/`
and `references/languages/`, orchestration in `references/workflow.md`,
synthesis in `references/verification.md`, and output fields in `assets/`.
- **Sibling skills (`skills/defect-review`, `skills/test-review`, `skills/perf-review`):**
separate read-only skills, each with its own contract, lenses or questions,
roles, and version, and zero runtime cross-dependency. Read
[the family design](docs/review-family.md) before changing boundaries, proof
bars, or roles across the four skills. Keep criteria strictly isolated: a
defect is not readability, a weak test is not a defect, slow code is not a
defect, and fast code that reads badly is not a performance finding.
- **Adapters (`adapters/`):** own native tool allowlists, model selection, and
result collection, never a second review policy. Version 3 ships no custom
source-reader or result-store runtime. Generated trees under `adapters/*/plugin`
and `adapters/codex/super-review` are delivery copies, not live authoring
targets.
- **Protected invariants:** preserve technical equivalence constraints, the
eight base Super Review lenses, all 56 stable rule IDs, fresh-context
subagent isolation, and configured worker model profiles unless the user
explicitly scopes a migration. Tool and role `description` fields are
model-visible instructions. Team code references illustrate explicit rules,
not extra authority. Keep evaluator expectations and holdouts out of reviewer
packets and installed skill resources.
## Writing instructions for agents
Every file an agent reads (`SKILL.md`, contracts, lenses, workflows, adapter
roles, `AGENTS.md`) is governed by the same levers so the agent runs a
predictable process without wasting attention:
- **Two loads and invocation:** always-loaded text (`AGENTS.md`, model-invoked
descriptions, base contracts) spends *context load* on every turn; explicit
slash skills spend *cognitive load* so the human chooses when they fire. All
four review skills are user-invoked (`disable-model-invocation: true`,
`allow_implicit_invocation: false` in `agents/openai.yaml`): keep trigger
descriptions single-sentence and human-facing (adding an explicit-request
gate only where a host lacks `disable-model-invocation`). Because user-invoked
skills cannot invoke one another, shared maintainer rationale belongs in
`docs/`, never as cross-skill runtime links.
- **Context pointers:** a link's *wording*, not its target file, decides when
an agent loads it. Front-load the leading term, state what the target holds,
give one trigger per genuine branch (collapse synonyms), and cut identity the
target already states. When an agent misses a required resource, sharpen the
pointer before inlining the file.
- **Information hierarchy and progressive disclosure:** rank content as
(1) *in-file steps* (ordered actions), (2) *in-file reference* (flat rules
used on every run of that role), and (3) *disclosed reference* behind a
pointer. Inline what every run of that recipient needs; push branch-only
material (`harnesses/*.md`, `#compact-pairs`, conditional profiles,
`continuation.md`) behind pointers so primary steps stay unburied.
- **Co-location against sprawl:** keep each concept's positive target, decision
rule, and `Keep when` preservation caveats under one heading in one
authoritative place per recipient path. Scattering fragments one rule across
files; duplication repeats it and inflates its weight. Repeat a rule only for
an independent fresh-context recipient that never loads the other file, or
for a distinct language-specific edge.
- **Checkable, exhaustive completion criteria:** visible later steps pull
agents toward *premature completion*. Resist that pull with binary *clarity*
(pinned SHAs, quoted lines, a survived challenge, mutant + witness, before
and after counts) and high *demand* ("every included declaration read in
full", "every hot path checked against Expect", "every reaching test
accounted for"). High demand drives *legwork* without spelling out micro-steps.
Split phases across real context boundaries (fresh subagent windows, never
conversation forks; keep orchestrator verification and report templates out
of worker packets).
- **Pretrained leading words and positive targets:** anchor behavior with
compact terms already strong in pretraining (*Design It Twice*, *Shotgun
Surgery*, *load-bearing*, *seam*, *mutant*, *witness*, *hot path*, *Amdahl's
law*), repeated as exact tokens rather than re-explained in paraphrases.
Front-load the positive target; steering by negation activates the forbidden
behavior. Write flat rules as `**Leading term**: burden -> target`, and use
no em-dashes in prose (rewrite with a colon, comma, period, parentheses, or
conjunction). Reserve `Never` for hard read-only, safety, or isolation
guardrails, paired immediately with what to do instead.
- **Environment over cache, intent over syntax, and no-op pruning:** state
what looking in the workspace cannot reveal: search anchors for non-obvious
problem classes, project taxonomy boundaries (`finding` vs `tradeoff`),
anti-folklore traps where pretraining defaults to false positives, and
harness or user constraints. Leave out what one lookup in the environment
reveals (manifests, directory layout, tool schemas, or dependency/stdlib
source on disk) and what a strong model already knows once pointed at the
problem: API call syntax and overload recipes, rewrite micro-templates,
version or protocol-limit tables, and third-party library internals (`LRU`
sizes, feature flags, middleware hooks). Concrete syntax recipes accrete
corner-case patches and go stale across versions; state semantic intent and
contract conditions instead. Test every sentence against the model's default:
if deleting it changes no behavior, delete the whole sentence rather than
trimming words, while keeping load-bearing constraints intact. When a real
run exposes a miss, generalize to the class of failure instead of accreting
incident-specific sediment.
- **Source-verified semantics and boundary equivalence:** verify every
language, runtime, or library claim kept in instructions or evaluation
fixtures against primary source on disk, official specifications, or the
local compiler/typechecker rather than memory (what actually allocates,
locks, flushes, coalesces, or short-circuits on both hits and misses). Before
classifying `X -> Y` as behavior-preserving, check `Y` against `X` across
boundary inputs (empty or out-of-range slices, non-ASCII or escaped text,
symlinks, cancellation, error/flush paths, atomicity, and public contracts):
express conditional equivalence as a compact semantic condition or `tradeoff`
boundary rather than inline code-guard recipes.
## Development, evaluation, and release
Settle the design before writing prose, and do not treat a model run as a
drafting step; running a review on a real repository is the maintainer's choice.
Load only the files relevant to the requested edit rather than the full
reference library or historical studies.
Edit canonical skills and adapter templates, rebuild generated packages, and
select checks by changed inputs in [CONTRIBUTING.md](CONTRIBUTING.md). When
changing an agent decision, follow [the evaluation protocol](evals/README.md):
run a bounded improvement cycle, pair each changed decision with contrasting
report/retain inputs isolated from grading expectations, and record actual
model/effort and raw failures alongside successes. Compile or typecheck code
fixtures with strict warnings against their declared language and dependency
versions, keep `report` and `retain` pairs symmetric on public API and
error/transaction contracts, and audit `retain` controls through every requested
lens so no unintended finding leaks in. Mechanical tests prove package and
fixture integrity rather than model judgment (anchor prose assertions on stable
headings and decision boundaries, not syntax examples); do not promote
experimental routing or pairing defaults on token savings alone.
Publication, tags, marketplace pins, local tool installs, and PR comments each
require explicit user scope. Published `v<version>` tags are immutable; follow
[the release rules](CONTRIBUTING.md#release) before tagging, releasing, or
updating marketplace pins.