standards: when a comment is found wrong, delete it — don't qualify it

Problem

The default repair for a comment a reviewer calls wrong is to add a sentence. Each added sentence is a new claim that nothing tests, so the next reviewer finds a new defect, which is answered with another sentence. The comment grows, gets less internally consistent, and the PR never converges.

Code has a failure mode. Prose does not — a wrong comment is 100% green forever. So the review surface is "is every sentence true?", which is unbounded and grows every time you answer a finding.

Evidence

TimZander/AudioClassifier#186 is a comment-only PR, on its seventh round. Its header went 13 → 45 lines across five commits, each one responding to review by adding explanation. A review of the result found 3 blocking defects and 21 findings — in prose whose entire purpose was accuracy.

The clearest instance: commit 5d85225 was fixing an ambiguity. In the same commit it added the sentence "the routing comments below call vendor/ immutable-per-version" and deleted that exact wording from the comment it points at. The fix created the defect. It took executing the diff to notice.

By the end, the 45 lines contained: a service-worker lifecycle paragraph that was backwards, a causal attribution to the wrong Cache-Control token, a claim that a function "treats quota-exceeded as a real failure" when it swallows it, and a size figure describing a build the product does not ship. None of it changed what a reader would do. All of it was added to satisfy a reviewer.

The rewrite deletes those four paragraphs rather than correcting them, and the header lands at ~28 lines — shorter and more accurate than the version six rounds of "improvement" produced.

Proposed — add to standards/CLAUDE.md

Fix a wrong comment by deleting it, not by qualifying it.

When review finds a comment inaccurate, the reflex is to add a clause. Resist it. Ask first: does this sentence change what a reader would do? If not, cut it — an explanation of mechanism is a claim with no test behind it and an unbounded review surface.

• State the rule; skip the derivation. A decision table a reader acts on beats a paragraph explaining why. If the mechanism is worth arguing about across review rounds, it is worth asserting in a test.
• Point at the test, don't restate its values. Numbers in prose rot silently. see foo.test.mjs does not.
• Say it once. A rule stated in three files drifts in three files. One statement, pointers elsewhere.
• If a comment block is growing across review rounds, that is the signal. The artifact is the wrong shape, not under-explained.

Corollary for reviewers: a review that returns 20+ findings on a comment-only diff is telling you about the artifact, not the author.

Why this is generic

Nothing about it is language- or project-specific. The failure mode is: prose has no failure signal, so review of prose has no natural bound, and the cheapest response to a finding (add words) makes the next round worse. That applies to any comment, docstring, README, or ADR in any repo.

Acceptance criteria

• standards/CLAUDE.md carries the rule, near the existing Code Review Standards (which already says "every line of code is a liability" — this extends it to prose).
• The reviewer-side corollary is included: growth across rounds is a signal about the artifact.
• The rule names the concrete test: does this sentence change what a reader would do?
• Cross-referenced from the docs/comment guidance so it is found when writing, not only when reviewing.

Start in standards/CLAUDE.md near the existing Code Review Standards section. Add the rule, the reviewer-side corollary, and the concrete test about whether a sentence changes what a reader would do, then cross-reference it from the documentation/comment guidance. Done means all four acceptance criteria are satisfied and the guidance is discoverable when writing comments.