Improve comment quality and flag comment slop during review

[stdevMac]

Motivation

Following internal feedback that AI-generated comment slop is creeping into the codebase, this does two things: cleans up a small focal set of low-value comments, and — more importantly — closes the gap that let them land by giving the automated review a comment-quality dimension.

This is grounded in our own rule (AGENTS.md):

Comments that merely restate the code are noise — don't add them, and remove them when you encounter them.

What this changes

Cleanup (7 comments across 5 files)

• SpmcRingBuffer / BloomFilter — drop the AI generated / AI-generated attribution, keep the substantive notes (the "will hang if called by multiple producers" warning and the RocksDB provenance).
• FlatDbManager — delete stream-of-consciousness narration (// First it go to here, // And here in parallel., // Then eventually...); keep the real performance note.
• ColumnDb — replace // Not sure how to handle... / // Maybe it should be... musings with an actual explanation, and fill the empty <exception> doc.
• KeccakHash — delete // Return the result. sitting above return output;.

Review steering (the durable part)

• .agents/skills/review/SKILL.md — the review skill now flags added comments that restate adjacent code, are tautological XML docs, or carry author uncertainty / generation residue (// AI generated, // not sure how to handle this, // as requested, bare // TODO). Held to the skill's existing >80% confidence bar, with an explicit do-not-flag list: comments that explain why, cite a spec/EIP, state an invariant, or warn the caller are good and must not be touched.
• .github/workflows/claude-review.yml — mirrors the rule as a Low-severity focus item. Low is deliberate: the mergeable gate only trips on Critical/High/Medium, so comment-quality notes surface as inline advice without blocking merges.

Why prevention over a big cleanup

An audit of the existing comment corpus came back essentially clean (~0.15% flag rate; the single biggest cluster is 2019-era human legacy, not AI). The corpus barely needs scrubbing — what needs controlling is new inflow, and the review bot was previously configured to only flag comments that contradict code, so restating/narration/residue passed straight through. This flips that.

Scope / safety

• Comment-only edits in the 5 source files — no behavioural change.
• The workflow edit is purely additive prose inside the existing prompt: block: no new run: step, no untrusted-input interpolation. YAML validated.
• Framed as comment quality, not "AI vs human" — enforceable regardless of authorship and no detector involved.

Deliberately not included (open for discussion)

• .github/copilot-instructions.md / Cursor rules to cover non-Claude AI entry points.
• A deterministic slop-lint CI check (ripgrep → reviewdog, added-lines-only) for the few near-zero-FP patterns.
• Empty-XML-tag cleanup (~28 <param></param>/<returns></returns> tags) — fill-vs-delete is a per-member judgement call.

[hudem1]

Nit The three removed comments here (// First it go to here, // And here in parallel., // Then eventually a compacted snapshot will be sent here where this will decide what to persist exactly) weren't pure restatement — together they sketched the three-stage pipeline (compactor → trie-node-cache populate, in parallel → persistence) and, in particular, the last one described the role of the persistence task, which isn't obvious from the _persistenceTask field name alone. The broken English justified rewording, but consider keeping a one-line note on _persistenceTask explaining that it receives compacted snapshots and decides what to persist. Optional — the surrounding code makes it inferable.