docs: state the maintainer bot as planned, and point at the 48 unrated entries - #22
Open
john-the-dev wants to merge 2 commits into
Open
docs: state the maintainer bot as planned, and point at the 48 unrated entries#22john-the-dev wants to merge 2 commits into
john-the-dev wants to merge 2 commits into
Conversation
The README's differentiator paragraph, its architecture diagram, CONTRIBUTING, and GRADING all describe an automated maintainer in the present tense. It does not exist: scripts/ holds build, lib and validate; the only workflow is validate.yml (pull_request + push, never scheduled); all 13 commits are human; there is no bot config. The 11 A grades came from one hand-written commit. Meanwhile 48 of 59 entries are grade: unrated, which the README's own "continuously-maintained, quality-graded" claim invites a visitor to check. Two things get fixed by saying so plainly: - The claim becomes true, and stays true whether or not the bot is built. Every edit is phrased as "planned, not yet running" rather than removed, so nothing here forecloses building it. - The 48 unrated stop being someone else's job. GRADING.md told a reader the bot would grade them, which is exactly the sentence that stops a contributor from doing it. README now names them as the good first contribution, with the rubric and the command that lists them. Validated: `node scripts/validate.mjs` -> 59 entries valid, 48 warnings, rc=0, identical with these docs and with the originals (docs are not validator input; run from a path without spaces — lib.mjs:66 does not decode %20). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Aug 31, 2026
"48 of 59 entries are grade: unrated" was true when written and false by the time this branch was pushed — #21 grades 58 of 59, and it was already open. A number whose truth depends on which of two open PRs merges first should not be in the README at all. The CTA now points at what validate.mjs reports rather than a snapshot of it, and names re-grading as equally welcome — which is the contribution surface that survives #21 landing.
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.
What
Four docs describe an automated maintainer in the present tense. It does not exist yet. This states it as planned and turns the 48 unrated entries into a named contribution surface.
Why — measured, not assumed
The bot is not running. Three independent checks:
scripts/containsbuild.mjs,lib.mjs,validate.mjs— no gradervalidate.yml, triggered onpull_request+push— never scheduled.github/app configThe 11
Agrades came from a single hand-written content commit.And the promise has a cost.
dist/kb.jsonis 48unratedof 59. The README sells "continuously-maintained, quality-graded" with "freshness + grading" as the differentiator, so a visitor who checks finds 81% ungraded — andGRADING.mdtold them a bot would handle it, which is precisely the sentence that stops a reader from grading one themselves.The edits
README.md:5README.md:26Sutando maintainer-bot[maintainer-bot: planned, not yet running]README.md:58CONTRIBUTING.md:21GRADING.md:13validate.mjswarns on each; grading them is open contribution workGRADING.md:38Every claim is phrased as planned, not deleted — this does not foreclose building the bot, it just stops the docs asserting it already runs.
Verification
Identical with these docs and with the originals — docs are not validator input, so this is a control confirming no regression rather than evidence the edit works.
One incidental finding, not fixed here:
scripts/lib.mjs:66builds afile://URL and passes it toreaddirSyncwithout decoding, so the validator crashes withENOENT ... Application%20Supportwhen the repo is checked out under a path containing a space. CI is unaffected. Happy to file it separately.Also worth knowing
By
GRADING.md's own rule (stale =last_verified> 90 days), zero of the 59 entries are currently stale — ages run 6 to 48 days. The only real content gap is the 48 unrated, which is what this PR points contributors at.