Removed the companion-project clause from the Sub-item definition in
CONTEXT.md's vocabulary. Its examples (aws-sdk-pandas under pandas,
flower under celery) went stale this sitting: those companions were
promoted, re-homed, or deleted. Per the maintainer's 2026-08-16 policy
decision, sub-items are now reserved for awesome-* also-see links only
- a companion project must earn a full Entry in its proper Use Case or
not be listed.
Co-Authored-By: Claude <noreply@anthropic.com>
Extend the known failure-mode list for PyPI download counts beyond
model weights to any project consumed outside pip (SDK downloads like
renpy, deployed services like thumbor). Also clarify that the per-Use-
Case Cap is a ceiling, not a floor: a freshly minted Use Case may hold
a single entry.
Co-Authored-By: Claude <noreply@anthropic.com>
Resolves decision 10's reservation on maintainer word: the 3+2/5 cap
numbers stay as written — across the full prune they held everywhere
except a handful of explicit overrides — and the override practice
itself becomes a written rule: the maintainer may exceed any limit
for a specific entry or use case by explicit decision, case-by-case,
carrying no weight for submissions. CONTEXT.md gains the matching
Override vocabulary entry.
Co-Authored-By: Claude <noreply@anthropic.com>
Maintainer correction to the previous amendment: stdlib sorts at the
top of the whole use case, not merely first within its tier. No README
movement results — the stdlib admission rule (a standard-library
module is listed only where it is itself the obvious choice) means
every stdlib entry already sits in the first tier, so tier-top and
use-case-top coincide; the rule text now states the intent directly.
Co-Authored-By: Claude <noreply@anthropic.com>
Maintainer rule change: built-ins lead their tier instead of sorting
last with the other no-signal entries — a stdlib module that earns a
slot is the default answer, so it reads first. Several stdlib modules
in one tier stay alphabetical. Non-stdlib no-signal entries (agent
skill packs, projects distributed outside PyPI) still sort last in
tier. README reorder of already-audited sections follows in a style
commit; unaudited sections pick the rule up at their own audit.
Co-Authored-By: Claude <noreply@anthropic.com>
The 2026-08-16 Database & Storage audit exposed a vocabulary gap: four adjudicated entries (clickhouse-driver, dogpile.cache, django-cacheops, django-haystack) are neither Obvious Choices nor trajectory-backed Challengers but demoted incumbents occupying Challenger slots, and the sitting had to improvise the term. The maintainer ratified it during review. A demoted incumbent counts against the two Challenger slots, but the adoption-trajectory bar gates only new admissions, not demotions.
Also from the same sitting: psycopg2 was deliberately left unlisted under Database Drivers > PostgreSQL (282M downloads/month as psycopg2-binary, pepy 2026-08-16) because psycopg 3 is the new-work answer and v2 is legacy install base. Recorded here so the next PostgreSQL audit knows it was a decision, not an oversight.
Co-Authored-By: Claude <noreply@anthropic.com>
Follow-up to d07440f: the definition's placement clause described only
companion projects (flower/celery), but awesome-* also-see lists are
Sub-items too.
Co-Authored-By: Claude <noreply@anthropic.com>
The device now has two precedents (aws-sdk-pandas under pandas, flower
under celery in the 2026-08-16 Web Development Audit) plus the awesome-*
links; future Audits need the term - an indented link that holds no slot
and rides its parent outside the Cap.
Co-Authored-By: Claude <noreply@anthropic.com>
Packages the audit process proven across the shortlist-reform sweeps
as a reusable skill: resolve scope from the arguments (AskUserQuestion
when ambiguous or absent), fetch live evidence for every entry
(BigQuery downloads, repo state, PyPI metadata), draft verdicts with
restructure-before-cap and tier promotions/demotions, review through
the verdict-preview page, execute one commit per section on explicit
go, and record durable conclusions into CONTRIBUTING.md, CLAUDE.md,
AGENTS.md, and CONTEXT.md. CONTEXT.md gains the Audit glossary term
(the reform sweeps were the first Audits). Rules stay single-sourced in
CONTRIBUTING.md — the skill carries process only.
Co-Authored-By: Claude <noreply@anthropic.com>
Maintainer decision 2026-08-16, amending the ordering half of the
Challenger-marking rule: within a use case, obvious choices still come
first and challengers still follow (position stays the marker), but
each tier now orders by PyPI downloads per month descending instead of
alphabetically. Entries without a download signal (stdlib modules,
agent skill packs) sort last within their tier, alphabetically.
Updated in CONTRIBUTING.md (Entry Ordering), CONTEXT.md (Challenger),
and CLAUDE.md (Key Rules).
Co-Authored-By: Claude <noreply@anthropic.com>
A 2026-08-15 grilling round replaced the Challenger marking
convention: within a Use Case, Obvious Choices are listed first
(alphabetically), then Challengers (alphabetically), with no marker
in the entry text. Update the Challenger definition in CONTEXT.md.
Co-Authored-By: Claude <noreply@anthropic.com>
CONTEXT.md review found several definitions had drifted from the
settled shortlist-reform decisions:
- Entry: pypi-name placeholder contradicted the serves-Python-developers
scope test, which explicitly treats implementation language and
packaging as irrelevant; now named by PyPI package name when one
exists, else repository name
- Subcategory: example referenced a name that no longer matches the
current README structure (Mock, not Mocking)
- Thematic Group: referenced elsewhere in the doc but never defined;
added
- Use Case, Obvious Choice, Split: updated to match the settled
cap/evidence/restructure decisions (maintainer-only structure
changes, PyPI-download judgment with known failure modes noted,
Split considered before trimming)
Co-Authored-By: Claude <noreply@anthropic.com>
Records the outcome of a grilling session with the maintainer that
settled the redesign of awesome-python from a catalog into a curated
shortlist of Obvious Choices per Use Case. Execution is held pending
maintainer go-ahead, so these files let a fresh agent resume without
re-litigating settled decisions:
- CONTEXT.md: glossary of the editorial vocabulary (Use Case, Obvious
Choice, Challenger, Displacement, Split, etc).
- docs/adr/0001-shortlist-not-catalog.md: the ADR recording the
decision, considered options, and consequences (status: proposed).
- .gitignore: docs/ was wholesale-ignored; carve out docs/adr/ so the
ADR can be tracked.
Co-Authored-By: Claude <noreply@anthropic.com>
Vinta ChenandClaude