ANTI-load-bearing CLAUDE.md

# Comment & prose style

Your default commenting and prose style is a known, catalogued failure mode: verbose, literary, tutorial-voiced, over-certain. It persists even against explicit instructions, so treat compliance as a process, not an intention: write, then re-read only the comments/prose as a separate pass against the rules below. Rules have IDs so they can be cited in review ("violates L2").

Scope: code comments, docstrings, commit messages, PR descriptions, README/doc prose written in this repo.

## W — What comments are for

- **W1** Comments explain *why*: why this exists, why this way over the obvious way, why it works when it looks wrong, what external constraint (protocol, business rule, upstream bug) forces it. Delete comments that restate adjacent code.
- **W2** Fact first, rationale second. Lead with the mechanical claim in plain declarative prose; the reason follows. Never an aphorism the reader must decode.
- **W3** Standard trade vocabulary only: token bucket, debounce, backpressure, memoize, bypass, invariant. Greppable names, never invented imagery ("on the glass", "down the wire").
- **W4** Falsifiable claims. Every comment must be checkable against the code and visibly break when the code changes. Include units, thresholds, boundaries: bytes vs chars, ms vs s, inclusive vs exclusive, base-0 vs base-1.
- **W5** Behaviour assertions ("this guarantees X") are usually better as a test named for X. Prefer the test; if commenting anyway, cite the test.
- **W6** When comment and code disagree, the comment is wrong. Fix the comment; flag the disagreement in your summary in case the code is the actual bug.
- **W7** Deliberate-but-uncommented decisions (a cap, a reset, an ordering constraint, a magic number) get 1–3 plain lines. Rationale gaps are where comment effort goes.
- **W8** Length: inline 1–3 lines; file/class headers ≤2 paragraphs; anything longer moves to a doc/ADR referenced by path.
- **W9** Register test: readable by someone tired, unfamiliar with the file, debugging at 2 a.m., eighteen months out, with no memory of any metaphor or of this chat.

## L — Banned lexicon

Do not use these in comments, docs, commits, or PRs. If one seems genuinely necessary (rare), justify it inline.

- **L1 Claude-tell metaphors:** load-bearing; seam(s); the shape of; does work / does real work / heavy lifting / earns its keep / quiet job; the magic happens; under the hood (decorative); journey; tapestry; delve; landscape (abstract); ecosystem (decorative).
- **L2 Certitude/bravado:** honest(ly); exact(ly) as filler; obviously; clearly; simply; just (as minimizer); the whole point; root cause (unless it demonstrably is); the key insight; crucially; importantly; fundamentally (as filler).
- **L3 Empty quality adjectives:** elegant; robust; clean(ly); graceful(ly); seamless; comprehensive; battle-tested; production-ready; performant; powerful; proper(ly) as filler; first-class; best-practice (as adjective).
- **L4 Corporate/SF filler verbs:** leverage; utilize (use "use"); streamline; wire up; land (for completing work); surface (as verb); orthogonal; synthesize (decorative).
- **L5 Decorative architecture-speak:** single source of truth / source of truth (unless naming an actual designated one); canonical (same condition); separation of concerns (as a comment's entire content).
- **L6 Emoji and decorative unicode.** Anywhere: comments, commits, PRs, console output strings.

## S — Banned structures

- **S1 Contrastive binary**, all variants: "isn't X — it's Y"; "not just X, but Y"; "not merely X"; "this is less about X than Y". Arrive at the point directly; don't stage a fake wrong answer to knock down.
- **S2 Aphoristic ender:** closing a comment block, commit, or PR with a short quotable maxim. If the final sentence has no identifier and no number and sounds like it wants quoting, delete it.
- **S3 Mirrored-clause symmetry** for rhetorical effect ("a key you press makes a key sound, text the machine sends makes a bleep").
- **S4 ALL-CAPS emphasis** (MUST, WHOLE, ONLY as shouting). Acronyms and language keywords excepted. If a distinction matters, the sentence carries it.
- **S5 Tutorial voice:** "now we...", "let's...", "first we loop over...", narrating readable code step by step.
- **S6 Chat leakage:** "as requested"; "per your instructions"; "I've added/simplified/fixed"; "Fixed!"; "You're right"; any first-person narration; any comment that only makes sense as a message to the person in this conversation.
- **S7 Em-dash chains.** More than one em-dash per comment block is a tell; restructure the sentence.
- **S8 Headers/sections in short docs** where three sentences of prose would do; bullet lists for content that is actually sequential prose.

## H — Self-check heuristics

Apply these to your own output in the review pass. They approximate a linter; run them as if they were one.

- **H1 Redundancy:** if ≥ roughly half the meaningful tokens in an inline comment appear in the next 1–2 code lines, it restates the code. Delete or convert to a why.
- **H2 Atmospheric:** any comment over ~15 words containing zero code identifiers, zero digits, and zero standard technical terms is prose, not documentation. Rewrite with a checkable claim or delete.
- **H3 Naked numbers:** a digit in a comment needs a unit or a named-constant reference. "wait 500" → "wait 500 ms (POLL_INTERVAL)".
- **H4 Stale numbers:** any number in a comment must match the code it describes. On mismatch, apply W6.
- **H5 Length:** inline block over 5 lines → move content to header; header over 2 paragraphs → move to doc.
- **H6 Read-aloud test** on headers and PR descriptions: if it sounds like it wants to be quoted, rewrite until it merely wants to be understood.

## P — Process

- **P1** Two passes, always: write, then re-read only comments/prose against L, S, H. Known self-review blind spots: binaries produced while paraphrasing a binary you were removing; aphoristic enders on headers; "honest"; em-dashes; "robust".
- **P2** Rewriting existing comments: translate, don't strip. Every genuine rationale in the original survives, restated per W. A file scrubbed of all "why" content is as much a failure as the literary original.
- **P3** Never change code to satisfy a comment rule. Comments and prose only, unless the task says otherwise.
- **P4** Commit messages: imperative subject ≤72 chars stating the change; body states why, constraints, and side effects in plain prose. All L/S rules apply. No "This commit introduces...".
- **P5** When a rule and readability genuinely conflict, readability wins — say so in one line where you break the rule.