docs(agents): the nine axes for reviewing a docs/design change - #387
Merged
Conversation
#386 ran five review passes over its own work and found seven issues; unaided prose reading found none of them. The difference was that each pass named an axis and compared against an artifact. Record the axes so the next docs/design change gets the same treatment without rediscovering them. Each axis carries the case that earned it, because the abstract form ("check coherence") is what produced the zero. The list also states what NOT to report -- the suite already enforces example lines, deviates: today-values, boundaries, the one-of implemented:/tracked: rule and citation excerpts, so a finding those would catch is a false positive. Written into AGENTS.md rather than shipped as tooling: .gitignore's tools block keeps .claude/, .codex/ and .gemini/ personal, and AGENTS.md is the file every assistant reads. A Claude Code subagent and /docs-review command exist locally and are noted as a convenience, with the axes here as the shared record. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #387 +/- ##
=======================================
Coverage 98.51% 98.51%
=======================================
Files 44 44
Lines 2895 2895
=======================================
Hits 2852 2852
Misses 43 43 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Two changes, one of them the checklist catching itself. The agent and /docs-review references come out. .claude/ stays personal per .gitignore's tools block, so a committed pointer to an untracked file is a dangling reference for everyone else; the axes are the shared record and stand alone. Running axis 1 (recompute every number) over this PR falsified the corpus-blindness count, which was wrong in two files merged by #386 as well as here. Of 782 corpus names 245 carry a comma, TWO of those end in a particle, and ONE clears P6's words-to-spare guard and actually moves -- "Nguyen, Van" is the second, held back by the very guard the rule needed. "Exactly one ends in a particle" conflated the population with the movers, which is the distinction that field note exists to draw. Corrected in mechanisms.md, decisions.md#P6 and AGENTS.md, with the mechanisms note recording that it made its own error inside the correction. The finding count is corrected with it: #386's passes surfaced ten issues, nine by these axes and one by the spec self-review. "Seven" was a mid-session tally that stopped being true two passes later and was never re-counted. Neither error changed an argument -- the corpus is near-blind at two names as at one, and the axes earn their place at nine as at seven. That is what the count-durability note asks for: phrase the argument so it survives the digits moving, then get the digits right anyway. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #386. Documentation only — one file.
Why
#386 ran five review passes over its own work and surfaced ten
issues — nine by the axes below, one by the spec self-review. Unaided
prose reading surfaced none. The difference was that each pass named
an axis and compared against an artifact rather than against memory.
Those axes existed only in that session's transcript. This records
them, each with the defect that earned it — the abstract form ("check
coherence") is precisely what produced the zero.
What's here
Nine axes in
AGENTS.md's rules-documentation section, plus thepopulation-size caution and a do-not-report list pointing at the two
test files that already machine-check the mechanical layer.
Scope is all four documents —
rules.md,decisions.md,mechanisms.mdandAGENTS.mditself, which carries the conventionsthe other three rest on. Axes 3, 5 and 6 need rule statements,
examples and
interacts:, so they arerules.md-only; the note saysso and asks reviewers to report what they skipped as inapplicable.
A checklist that asks for something meaningless teaches the reader to
skim it.
The checklist caught itself, three times
Running the axes against this PR found three issues, two of them in
files merged by #386:
Axis 1 — the corpus-blindness count was wrong.
Nguyen, Vanis the second, held back by the very guard P6 needed."Exactly one ends in a particle" conflated the population with the
movers — the distinction that field note exists to draw — so the note
made its own error inside the correction. Fixed in
mechanisms.md,decisions.md#P6and here.Axis 1 — the finding count. "Seven" was a mid-session tally that
stopped being true two passes later and was never re-counted.
Axis 7 — the skip-list under-reached. It named five
machine-checked things where there are nine doc tests, so a reviewer
could have burned effort reporting a broken
interacts:ID or anunresolved cross-doc anchor. Now complete, pointing at the test files
as the authority and saying outright that it goes stale as guards are
added.
Neither count error changed an argument — the corpus is near-blind at
two names as at one, and the axes earn their place at nine as at
seven. That is what the count-durability note asks for, and it is
also why neither was catchable by reading.
Why prose and not tooling
A Claude Code subagent and
/docs-reviewcommand were built and work,but
.gitignore's tools block keeps.claude/,.codex/and.gemini/personal. They stay on one machine and are notreferenced here — a committed pointer to an untracked file is a
dangling reference for everyone else. A
PostToolUsereminder hookwas also built and validated, then dropped in favour of this note.
Verification
uv run --frozen pytest— 3459 passed, 20 skipped, 11 xfailed, greenat every commit. Axis 9 checked:
AGENTS.mdis not input to any docparser (
SWEEP_DIRSis nameparser/tests/tools,.pyonly).🤖 Generated with Claude Code