From adccce24474eea63e6f0269f94b54e39111fba43 Mon Sep 17 00:00:00 2001 From: john-the-dev <52230987+john-the-dev@users.noreply.github.com> Date: Mon, 31 Aug 2026 06:55:15 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20the=20maintainer=20bot=20does=20not=20e?= =?UTF-8?q?xist=20=E2=80=94=20say=20what=20is=20true,=20and=20ask=20for=20?= =?UTF-8?q?help?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README, CONTRIBUTING and GRADING describe an automated maintainer that proposes entries, grades unrated ones and flags stale ones. There is no such bot: every commit is human-authored, validate.yml runs only on pull_request/push, and no app config exists under .github/. The costly line is GRADING.md's "the maintainer bot grades these on its next pass" — it tells a reader the 48 unrated entries are queued for automatic grading, so the repo's single largest contribution surface reads as taken. Replaces the five claims with what is true, and turns the gap into the ask: 48 of 59 entries are unrated, validate.mjs names every one, and grading one is the best first PR. --- CONTRIBUTING.md | 6 ++++-- GRADING.md | 4 ++-- README.md | 6 ++++-- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c0dc4d3..f680396 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,6 +18,8 @@ Thanks for helping keep AI-agent engineering knowledge accurate and fresh. - **Lessons are public-only.** `category: lessons` entries must come from famous, publicly-documented projects/post-mortems. Never include private, proprietary, or non-public project details (anyone's). - **Primary sources first** — official docs / papers / release notes over secondhand blogs. -## The maintainer bot +## Automation -An automated maintainer (Sutando) also opens PRs — proposing new entries from the latest releases/research and flagging entries whose `last_verified` is >90 days old. Bot PRs are reviewed and merged by a human, same as any other. +CI validates the schema and rubric on every PR; `node scripts/validate.mjs` runs the same checks locally and lists every `unrated` entry and every entry past the 90-day staleness bar. + +There is **no bot proposing or grading entries** — grading requires independent sources a human has actually read, which is the whole point of the rubric. If that changes, this section changes with it. diff --git a/GRADING.md b/GRADING.md index 0cca5c0..c428652 100644 --- a/GRADING.md +++ b/GRADING.md @@ -10,7 +10,7 @@ Grades exist so "bad tech" and "outdated knowledge" are **evidence-based, not op | **B** | Solid and useful, with caveats. Maintained but niche, or accurate-but-aging, or best-for-specific-cases. Note the caveat in `evidence`. | | **C** | Use with caution. Slowing maintenance, partial adoption, known rough edges, or partially superseded. | | **D** | Discouraged. Deprecated, abandoned, superseded, or carrying unresolved security/correctness issues. Kept for the historical record and to warn readers — set `status: deprecated` (or `superseded`) and fill `superseded_by`. | -| **unrated** | Seeded or newly-added, not yet evidence-graded. The maintainer bot grades these on its next pass. | +| **unrated** | Seeded or newly-added, not yet evidence-graded. Nothing grades these automatically — an unrated entry is an open task, and `scripts/validate.mjs` lists them all. | ## Signals (what `evidence` should cite) @@ -35,4 +35,4 @@ Each `evidence` item should be a dated, checkable statement, e.g.: ## Staleness -An entry is **stale** when `last_verified` is more than **90 days** old. The maintainer bot flags stale entries in a `review-needed` PR; a human (or the bot with evidence) re-verifies and updates `last_verified` + `grade`. +An entry is **stale** when `last_verified` is more than **90 days** old. `scripts/validate.mjs` flags them; a human re-verifies and updates `last_verified` + `grade`. diff --git a/README.md b/README.md index a692219..0ce32db 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A continuously-maintained, **quality-graded** knowledge base of AI-agent engineering — frameworks, orchestration, evaluation, memory, tools, protocols, security, and research. -Most "awesome" lists rot: agent tooling ships breaking changes monthly, and stale entries mislead more than they help. This repo's differentiator is **freshness + grading**: every entry carries a `status`, a `last_verified` date, and an evidence-backed `grade`, and an automated maintainer bot proposes additions and flags stale entries for review. +Most "awesome" lists rot: agent tooling ships breaking changes monthly, and stale entries mislead more than they help. This repo's differentiator is **freshness + grading**: every entry carries a `status`, a `last_verified` date, and an evidence-backed `grade`, and every entry is graded by a human against a published rubric. It's **dual-use**: - **Human-browsable** — one markdown file per entry under [`entries/`](entries/). @@ -55,7 +55,9 @@ Entries are graded **A/B/C/D** on an evidence-based rubric (see [`GRADING.md`](G ## Contributing -PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). CI validates every entry against the schema + rubric. The maintainer bot opens PRs too; humans review and merge. +PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). CI validates every entry against the schema + rubric. + +**The best first contribution is grading an `unrated` entry.** 48 of 59 entries are `unrated` today — `node scripts/validate.mjs` names every one of them. Pick one, find the independent sources the rubric asks for, and open a PR with `grade` + `evidence[]` filled in. ## Status