# Comments About Code Not Change

> >

- **Type:** Skill
- **Install:** `agentstack add skill-serhiy-bzhezytskyy-contrib-receipts-comments-about-code-not-change`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [serhiy-bzhezytskyy](https://agentstack.voostack.com/s/serhiy-bzhezytskyy)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [serhiy-bzhezytskyy](https://github.com/serhiy-bzhezytskyy)
- **Source:** https://github.com/serhiy-bzhezytskyy/contrib-receipts/tree/main/skills/comments-about-code-not-change

## Install

```sh
agentstack add skill-serhiy-bzhezytskyy-contrib-receipts-comments-about-code-not-change
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Comments about the code, not the change

## Purpose

A source comment is read by someone opening the file cold in a year — not by
someone following your PR. So it must describe what the code *does and why*, in the
present tense, as if it were always this way. The moment a comment references the
change that produced it — an issue number, a PR number, a maintainer's @handle,
"the previous code did X", "close-enough mistake", "aligned per #NNNN" — it stops
being documentation and becomes change-narrative that belongs in the PR and commit,
where it is contextual and doesn't rot. Maintainers across projects call this out
as a top AI tell; it's a cheap, high-frequency source of "this reads like slop".

Exception: a **test** that guards a specific regression MAY cite the issue number in
a comment — that links the test to what it protects, and projects do this. Even
there, keep it to the ticket ref, not a change-narrative or an @handle.

## When to use

- Before committing any code change to a repo you don't own.
- Any time you write a comment that only makes sense to someone reading the PR.

## When NOT to use

Docstrings/comments that explain *behavior* — even long ones — are fine; this only bans change-narrative (issue#, @handle, "previously"), not thorough documentation.

## The practice (checklist)

- [ ] Write comments in the **present tense**, describing behavior and the reason
      for it — as if the code were always this way.
- [ ] Keep OUT of source: issue numbers, PR numbers, maintainer @handles,
      "confirmed by X", "the previous code did Y", "aligned per", "close-enough".
- [ ] Before pushing, **grep the diff's added (`+`) comment lines** for `#[0-9]`,
      `@[a-z]`, "previously", "used to", "was a mistake", "aligned", "confirmed by".
      *Done when* the grep has been run over the real diff and returns nothing, or
      every hit is a regression test's ticket ref (the one exception below).
- [ ] Move any change-context you find to the PR description / commit message.
- [ ] Test-only exception: a regression test may cite its ticket ref, nothing more.

Treat the pre-push comment grep as **mandatory**, not a "remember to" — this is a
pattern people regress on across projects even after learning it.

## Rationalizations

| Shortcut | Why it fails |
|---|---|
| "One `// see #NNNN` is harmless." | It's the #1 AI tell; a reviewer greps the diff and the whole PR reads as slop. |
| "This context is useful — the reader should know what changed." | The reader opens the file cold in a year; change-context rots. It belongs in the PR body and commit, where it stays contextual. |
| "It's a test, so an issue ref is fine everywhere." | Only a regression test may cite its ticket ref — and only the ref, never an @handle or a change-narrative. |

## RECEIPT

**A Solr committer, apache/solr PR #4632** (`corpus-solr-prs/pr-solr-4632.json`, review
comment) — verbatim:

> "this wording here is indicative of a bug fix in the process of development but
> isn't useful in the delivered documentation. Of course 'not just the first'. AI
> loves to do this."

**Cross-project confirmation (journal) — a universal OSS norm, not one reviewer's
taste:**
- **Solr** — AGENTS.md §52: "changes shouldn't have code comments communicating the
  change."
- **Jetty** — a maintainer's first review comment on PR #15435: "Please remove this
  comment as the git history should be all the context needed."
- **OpenSearch** — #17140: an `advance()` comment shipped with "aligned per #17140…
  confirmed by @[maintainer]"; it was the only issue#/@handle comment in the whole file
  (zero precedent), rewritten to terse present-tense behavior.

## Lifecycle

- **Signals it worked:** no reviewer flags a comment as change-narrative or "AI
  loves to do this"; comments still make sense read cold, out of PR context.
- **What to log on a misfire:** the exact comment text a maintainer flagged and the
  file — recurring offenders (issue#, @handle, "previously") sharpen the grep list.
  Record it in [`LEDGER.md`](../../LEDGER.md).
- **Death criterion:** none foreseeable; it's a stable cross-project norm.
- **Relates to:** sibling to verify-before-a-committer-comment (both are "don't put
  unverified/irrelevant narrative in front of a maintainer"). This one governs source
  comments specifically, not the PR text.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [serhiy-bzhezytskyy](https://github.com/serhiy-bzhezytskyy)
- **Source:** [serhiy-bzhezytskyy/contrib-receipts](https://github.com/serhiy-bzhezytskyy/contrib-receipts)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-serhiy-bzhezytskyy-contrib-receipts-comments-about-code-not-change
- Seller: https://agentstack.voostack.com/s/serhiy-bzhezytskyy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.