Skip to content

docs: anchor the anti-bloat lens for PRs that have no directive - #287

Merged
cnighswonger merged 1 commit into
mainfrom
docs/anti-bloat-lens
Jul 31, 2026
Merged

docs: anchor the anti-bloat lens for PRs that have no directive#287
cnighswonger merged 1 commit into
mainfrom
docs/anti-bloat-lens

Conversation

@vsits-proxy-builder

Copy link
Copy Markdown
Contributor

Problem

The global reviewer baseline flags bloat that is "clearly larger than the directive's requirements justify." Community PRs have no directive, so the bar has nothing to anchor to and the finding silently degrades to "None."

Measured across the eight open community PRs: every single review reported Bloat / Non-Functional: None — including on a PR adding 6,630 lines of new production code with less test than code. The reviewer was following its instructions correctly; the instructions had a hole.

CLAUDE.md:84 already says "the reviewer-side anti-bloat lens lives in this repo's AGENTS.md." It didn't — AGENTS.md contained zero mentions of bloat. This makes that pointer true.

Change

AGENTS.md — for a PR with no directive, anchor to the defect it claims to fix: what is the smallest change that fixes the stated problem, and how much larger is this? Requires the size numbers be reported in every review, even when the verdict is "proportionate" — a stated number is checkable, "None" is not.

Calibrated against three PRs merged today, all proportionate:

PR prod LOC test:prod
#274 7 code + 19 comment 23.0x
#277 9 code + 10 comment 9.0x
#261 23 code + 31 comment 8.4x

Numbers verified against the merge commits, not the PR bodies.

Two explicit non-findings, because both are high here by design and a naive lens would flag them: test volume is not bloat, and comment lines exceeding code lines is not bloat when the comment records a defect's mechanism. Every merged example above has more comment than code and all three are better for it.

Also adds an attention item (not a blocker) for community PRs over ~300 production LOC missing a ## Non-Functional Requirements section, and instructs the reviewer to independently assess Load-bearing? rather than accepting the author's — that classification decides whether a human reviews before merge, so an author's "no" on a wire-contract change is a blocking finding.

CONTRIBUTING.md — new. AGENTS.md and CLAUDE.md are already committed and public, but both are addressed to our own agents; a contributor had nothing written to them. This points them at both files, explains which sections are internal, and asks for the non-functional checklist on larger PRs. It also documents things contributors currently have to infer: fork PRs don't get CI (and that's not their problem), we won't push to their branch, draft means draft.

Non-Functional Requirements

  • Size/complexity budget — 68 lines in AGENTS.md, 83 in a new CONTRIBUTING.md. Documentation only; no code.
  • Threat model — n/a. No inputs, no trust boundaries, nothing on the wire.
  • Maintainability — no new abstraction. The AGENTS.md section narrows an existing global rule for a case it didn't cover, and records why so it isn't "simplified" away later.
  • Performance/reliability — n/a.
  • Load-bearing? No. Documentation governing review behavior. No shared abstraction, wire contract, or schema.

Testing

Documentation only — no test surface. The calibration figures were computed from the merge commits (540981a, 5a9dac0, 8b25dc9) rather than quoted from PR bodies; two of my initial numbers were wrong and were corrected against the measured values.

Note

Pushed without GIT_PUSH_GUARD_ALLOW=1. Earlier pushes today needed it because pushing by tokenized URL makes the pre-push guard resolve $1 as the URL, fail to find a remote ref under it, and fall back to the empty-tree baseline — scanning all reachable history. Pushing by remote name with the token in an http.extraheader gives the guard its intended baseline. That was my bug, not the hook's.

— Proxy Builder

The global reviewer bar is "larger than the directive's requirements
justify." Community PRs have no directive, so the bar had nothing to
anchor to: across eight open community PRs every review reported
"Bloat: None", including one on 6,630 lines of new production code.

AGENTS.md now anchors no-directive PRs to the defect being fixed, and
requires the size numbers be stated in every review — a number is
checkable, "None" is not. Calibrated against #274/#277/#261, all merged
and all proportionate, so the reference is real work rather than a
guess. Explicitly excludes test volume and why-comments from the
finding, since both are high here by design.

CONTRIBUTING.md is new: AGENTS.md and CLAUDE.md were already committed
but are addressed to our own agents, so contributors had no file that
spoke to them. Points them at both, and asks PRs over ~300 production
LOC to carry the non-functional checklist.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GvZKP1JeXgHFCovTaAPT5B
@cnighswonger cnighswonger added documentation Improvements or additions to documentation approved-by-lead Final implementation approval from project lead ready-for-merge Required reviews are complete and no known blockers remain labels Jul 31, 2026
@cnighswonger
cnighswonger merged commit 81f47a5 into main Jul 31, 2026
5 checks passed
@cnighswonger
cnighswonger deleted the docs/anti-bloat-lens branch July 31, 2026 17:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved-by-lead Final implementation approval from project lead documentation Improvements or additions to documentation ready-for-merge Required reviews are complete and no known blockers remain

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant