Comment Cleanup

Models over-comment. They narrate the obvious, restate the signature, and explain the caller's job back to the caller. This skill removes that and leaves the comments that carry information the code cannot.

Only comment text changes. Code never changes.

Scope

• With arguments: the named files or globs.
• Without arguments: the files changed in the working tree (git status --porcelain, plus git diff --name-only against the fork point if on a branch).
• Never touch: vendored directories, generated files (# Code generated by, @generated, lockfiles), and anything gitignored.

State the file list before editing. If the list is over ~15 files, confirm first.

The loop

Run phase 1 → 2 → 3 over one file at a time. Then run the whole loop again on that file. Stop after 3 passes, or at a fixpoint. A pass that deletes nothing is a fixpoint only if you can state, for every survivor, the concrete misreading it prevents. If you cannot state it for one, that one goes and the pass continues. A pass that only reshuffles words is not progress.

Your own comments are the primary suspects

If you wrote this code in this session, every comment in it is suspect. You will read your own comment as informative because you remember writing it. What made it feel worth writing was the reasoning you did to write the code — that is not the reader's problem. Judge from the code alone and lean on deleting.

Phase 1 — Added value

For every comment, run the deletion test: delete it, read the surrounding code as a stranger, and name the specific thing you would now get wrong. If you cannot name one, it stays deleted. "It's useful context", "it's a why", "it helps a newcomer" are not answers — the answer is a concrete misreading.

Judge clause by clause, not comment by comment. A comment that passes the test on its second sentence does not keep its first.

Delete

• Restatement. // increment the counter over counter++. A docstring summary that re-spells the function name.
• Lead-in restatement. A first sentence naming what the code is, followed by the sentence carrying the real fact. Delete the lead-in and keep the fact. Do not merge them into one smoother sentence — that is how restatement survives a pass.
• Re-derivable motivation. "This is big", "for the record", "sorted so it reads first". If the reader can reconstruct the reason from the code in a few seconds, it is not a why.
• Signature echo. :param user_id: the user id, @returns {User} the user. Types and names already say it. Keep a param line only when it adds a unit, a range, an ownership rule, or a non-obvious default.
• Caller-directed narration. "Callers should catch this so they can retry", "raises so that the scheduler in queue.py can back off". The exception type and message carry this. A function does not document its callers.
• Tutorial comments. Explaining what map, a context manager, or a null check does.
• History and process. "Refactored to use X", "previously we looped here", "added in v2", "TODO: cleaned up" — unless it is a real constraint, this belongs in git.
• Section banners in a function short enough to read at once (# --- validation ---).
• Filler openers. "This function...", "Helper that...", "Simple utility to...".
• Comments that are already wrong. Delete, do not repair, unless the intent is obvious and worth keeping.

Keep

• Why, not what — and only a why that points outside this function: library behaviour, an upstream bug (with the link), another process or thread, a spec or RFC, an ordering constraint, an interaction that looks wrong and is not. If the whole story is visible in the file, the code is the story.
• Contract facts absent from the types. Units, ranges, mutation, thread-safety, idempotency, lifetime and ownership, complexity, side effects.
• Traps. Code that looks like a bug and is not. This is the highest-value comment in any file.
• Tool directives and legal text. # noqa, # type: ignore, @ts-expect-error, eslint-disable, #pragma, SPDX headers, license blocks, copyright.
• Tracked markers. TODO/FIXME/HACK that carry a ticket reference or a concrete condition.

Load-bearing docstrings — check before deleting

A docstring is sometimes code. Deleting these changes behavior:

• Click, Typer, and argparse render docstrings as --help text.
• FastAPI and OpenAPI generators publish them as API descriptions.
• Doctests inside a docstring are tests.
• Published API reference builds (Sphinx, godoc, rustdoc, TypeDoc, JSDoc) consume them.
• A docstring that is the only statement in a body — removing it leaves a syntax error. Insert pass or ..., or keep the docstring.

When a project enforces docs on public symbols (pydocstyle, ruff D rules, jsdoc/require-jsdoc, #![warn(missing_docs)]), trim those docstrings but do not remove them.

Phase 2 — Fit the file

Phase 1 judges each comment alone. Phase 2 judges the set. It can only delete or shorten — it can never save a comment Phase 1 condemned. Read the whole file, and one or two sibling files, and align:

• Density. Only ever a reason to delete. A missing comment is not an outlier; a lone documented private helper is.
• Symmetry is not value. "The sibling has one" says nothing about whether yours earns its place. If the neighbours are filler, the neighbours are what this skill exists to remove — delete yours and leave theirs alone, since they are out of scope.
• Form. One convention per file: Google or numpy or reST, // or ///, sentence case or lowercase, trailing period or none, imperative ("Return the user") or third person ("Returns the user"). Match what the majority of the surviving comments already do.
• Weight. If everything else in the file is a one-line comment, a surviving three-paragraph block is still too much. Compress it.
• Placement. Keep the file's habit for above-the-line versus trailing comments. Do not move a comment to a new line to satisfy taste.

If the file's convention is itself the over-commented style the user is complaining about, the file is the unit being fixed — set the new convention from the trimmed result, do not restore the old one.

Phase 3 — ste-writing

Invoke the ste-writing skill on the surviving comment text.

• Use its rewrite mode, not write or review.
• Mode STE-flavored for docstrings and multi-sentence block comments.
• Mode strict for one-line comments, warnings, and anything a reader hits mid-scan.
• Apply it to prose only. Identifiers, code samples inside docstrings, command syntax, URLs, and error strings stay verbatim.
• Shorter output from this phase can expose a comment as pure restatement. That is what feeds the next loop iteration.

To lint, extract the surviving comment text to a scratch file and score it — ste-lint.py reads prose, not source:

python3 ~/.claude/skills/ste-writing/ste-lint.py comments.md

Do not gate the loop on the score. A comment block is a few sentences, so the per-100-word rate is noisy at that length. Use it to catch a category you missed, not as a pass mark.

Verification

After each file:

1. git diff -U0 -- <file> and read it. Every -/+ line must be a comment, a docstring, or a pass/... inserted for an emptied body. If a code line moved, revert and redo.
2. The file still parses. Run the project's formatter or linter on that file if one is configured.
3. Run the tests once at the end, not per file, if the suite is fast.

Report

Per file: comments removed, comments trimmed, comments kept, and passes taken. Then list every survivor, one line each, naming the concrete misreading it prevents. A survivor you cannot justify in one concrete line should not have survived — go back and delete it. Do not commit.

Don'ts

• Do not edit code — no renaming a variable to justify deleting its comment, no reformatting, no dead-code removal. Those are /simplify.
• Do not delete a comment because it is long. Delete it because it is empty.
• Do not add comments. This skill only removes and rewrites.
• Do not spread to files outside the stated scope.
• Do not keep looping to look thorough. Two passes usually reach the fixpoint.