Skip to content

Commit fd81b8b

Browse files
derek73claude
andcommitted
docs(agents): put AGENTS.md itself in the axes' scope
This file carries the conventions rules.md, decisions.md and mechanisms.md rest on, and it has the same failure modes -- demonstrated in the previous commit, where axis 1 falsified two counts in the axes note itself. So the trigger now names four files, not three. Not wholesale, though. Axes 3, 5 and 6 need rule statements, examples and interacts:, which only rules.md has; asking a reviewer to run rule-vs-its-own-examples against AGENTS.md is asking for something meaningless, and a checklist that does that teaches the reader to skim it. The note says which six apply and asks the reviewer to report what they skipped as inapplicable. Checking that also ran axis 7 (general clause vs actual scope) over the skip-list, which named five machine-checked things where there are nine tests -- a reviewer could have burned effort reporting a broken interacts: ID or an unresolved cross-doc anchor, both already enforced. The list is now complete and points at the two test files as the authority, saying in as many words that it goes stale as guards are added. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent 7e6211b commit fd81b8b

1 file changed

Lines changed: 19 additions & 6 deletions

File tree

AGENTS.md

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -135,16 +135,29 @@ from the weakest instrument manufactures confidence rather than
135135
supplying it.
136136

137137
**Reviewing a docs/design change: the nine axes.** Run these before
138-
merging anything that touches rules.md, decisions.md or mechanisms.md.
138+
merging anything that touches rules.md, decisions.md, mechanisms.md —
139+
or THIS FILE, which carries the conventions those three rest on and
140+
has the same failure modes. Axes 3, 5 and 6 are rules.md-specific
141+
(they need rule statements, examples and `interacts:`); the other six
142+
apply to any of the four. Say which axes you ran and which you skipped
143+
as inapplicable — a checklist that asks for something meaningless
144+
teaches the reader to skim it.
139145
Each was earned by a defect that survived every other check on #386,
140146
where the review passes surfaced ten issues in total — nine of them
141147
by these axes, one by the spec self-review above — and unaided prose
142148
reading surfaced none. The parenthetical is the case that earned the
143-
axis. Skip
144-
what the suite already enforces — example lines, `deviates:` today-
145-
values, boundaries, the one-of `implemented:`/`tracked:` rule, and
146-
citation excerpts are all machine-checked, so a finding those would
147-
have caught is a false positive.
149+
axis.
150+
151+
Skip what the suite already enforces. `tests/v2/test_rules_doc.py`
152+
and `tests/v2/test_doc_citations.py` machine-check example lines and
153+
their `deviates:` today-values, boundaries, the one-of
154+
`implemented:`/`tracked:` rule, `implemented:` against the modules
155+
that actually cite the rule, `interacts:` and cross-doc anchor IDs,
156+
citation excerpts quoted verbatim, and legacy citation forms. Assume
157+
they pass; a finding one of them would catch is a false positive.
158+
Read those two files rather than trusting this sentence — it named
159+
five of the nine guards when written, and goes stale as guards are
160+
added.
148161

149162
1. **Recompute every number.** Any count, ratio or "N names" in the
150163
diff gets recomputed by a script written now, never read. (A

0 commit comments

Comments
 (0)