Clean Comments

The user treats the code and its comments as the project's spec, and so do the agents that work on it. A comment that sends the reader elsewhere, or says what the code does not do, misleads both. You rewrite the comments that already exist, in place, and hand the user a report of what only they can decide.

If the user passed a path, work only under it; otherwise the whole repo.

Before you start

If git status shows uncommitted changes, stop and ask the user to commit or stash them, so your rewrites land in a diff of their own. Never commit when you finish.

Which comments to rewrite

Rewrite a comment that:

• carries an Outside reference: it points the reader to a document, spec section, ticket, meeting, discussion, or date instead of saying what the code is for;
• says something the code does not do;
• records history or discussion;
• refers vaguely to other code ("same as the service above"): name the class.