Comment Audit

Strips the comments that repeat the code and keeps the ones carrying facts the code cannot state.

reviewingcommentsreadabilitycleanupminutes

When to reach for it

After a burst of generated code, when the file has a comment above every line and you still cannot tell why any of it is the way it is.

What changes

Comments that restate the line below them get deleted, so what remains is worth stopping to read.
Comments recording a reason, a limit, or a bug someone already hit are kept, and sharpened where they are vague.
A comment that contradicts the code is raised as a decision for you — the comment is stale, or the code lost a behavior somebody intended.
Banners, dividers and end-of-function markers come out, and the file gets split or renamed instead.
Places that need a comment and have none — a magic number, a deliberate delay, an order that matters — get one line saying why.

Pairs with

SKILL.mdpaste into your agent

Comment Audit

Go through the comments in this file and decide, one at a time, which earn their space.

1. Sort every comment into one of four piles

Restates the code — "increment the counter", above the increment.
States a reason — why this approach and not the obvious one.
States a constraint — a fact from outside the code: a service that rate-limits at ten a second, a browser bug, a vendor that sends numbers as strings, a rounding rule from the finance team.
Lies — it describes code that is no longer there.

2. Act on each pile

Restates — delete. If a line needs a comment to be readable, the fix is a better name or a smaller function.
Reason — keep, and sharpen if vague. "For performance" becomes "the straightforward version took four seconds on a ten-thousand-row export".
Constraint — keep, and make it checkable. Include the number, the version, the ticket, the date. A constraint with no source cannot be re-verified when the world changes.
Lies — do not just delete. Work out whether the comment is stale or the code is wrong, and say which. A comment describing behavior the code has lost is sometimes the only record that it was ever intended.

3. Remove the decoration

Banner comments, rows of dashes, section dividers, and end-of-function markers. If a file needs signposts to navigate, the answer is a smaller file.

4. Find what has no comment and needs one

The opposite failure is rarer but real. A magic number, a deliberate wait, an ordering that matters, a workaround that reads like a mistake — each needs one line saying why, or somebody will helpfully remove it.

5. Read the file top to bottom

Every surviving comment should tell you something the code cannot.

Rules

Do not delete a comment you do not understand. Not understanding it is evidence that it holds information you do not have.
Do not keep a comment because deleting it feels like losing work.
Do not write a comment to apologize for code you could simply fix.
Do not leave a TODO with no name and no condition. "TODO: handle this" is a comment that will outlive the project.