Comment Stinky

A code-comment smell detector and a write-time gate, in any language. It exists because of one specific failure mode. A coding agent's working context is a diff, so it writes comments aimed at whoever reviews that diff. The diff is transitory. The comment is permanent. One commit later the comment describes a state nobody can see, and the reader who needed to know why the code is shaped this way gets a paragraph about a change instead.

The rule the whole skill reduces to: write for a reader who has only this file open and does not know that a change ever happened. The reasoning behind it is in comment-audience.md, and why agents specifically break it is in agent-context-collapse.md.

Three operating documents. Read the one the task needs. taxonomy.md is the positive half, the nine kinds of comment worth writing and where every other kind of information actually belongs. catalog.md is the smell catalog, six pillars and 37 categories with detection signals, fixes, exceptions, and sources. write-gate.md is the four-question gate plus the trigger-phrase table and the rewrite recipes.

What it sniffs for

Six pillars, 37 categories, in catalog.md. The background models live as linked concepts under references/concepts/; read one when a finding needs the model explained, not just named.

1. Change narration. The signature agent smell. A comment that describes the edit rather than the code: diff narration (now, no longer, used to), ghost references to code that is not in the tree, comparatives measured against the deleted version, changelog text parked in the source, reviewer defense, prompt echo, session residue, eulogies for deleted code, commented-out code.
2. Redundancy. Comments that restate the code, doc comments that echo the signature, step-by-step narration of obvious lines, banner ceremony, and tutorial voice explaining the language rather than this code.
3. Missing intent. The comments that should exist and do not: unexplained constants and thresholds, workarounds with no named cause, deliberate deviations from convention, silent ordering dependencies, swallowed errors and empty blocks, unstated invariants, unexplained tradeoffs, and regression guards with no provenance.
4. Truth and decay. Comments that contradict the code, doc comments that lie about parameters or errors, anchors pointing at moved line numbers, files, symbols, and dead URLs, rationale copied to several sites that then drifts, and invariants stated only in prose that a type or assertion could hold.
5. Placement and form. Rationale at the wrong altitude, a comment that wants to be a name, a test, or a type, // where the ecosystem's doc-comment form is what tools read, essays where two sentences do, and debt with no owner, ticket, or condition (bare TODOs, and the undated "for now" that never gets listed anywhere).
6. Voice. First-person authorship, hedging, overclaiming safety nothing backs, and decoration.