| name | comment-audit |
| description | Audit and fix the comments in one or more source files against the repo's comment rules (plain declarative prose, no epigrams — CLAUDE.md |
Comment audit
Audit the comments in source files against the rules in CLAUDE.md ### Comments, fix what
fails them, and record the audit in a committed ledger at .claude/comment-audit-ledger.json.
An entry stores the file's git blob hash at audit time, so a file counts as stale once its
content changes after the audit — independent of commits, branches, or clocks.
Evaluate each comment in the file. Make sure you check every single comment. Do not miss
a single one. This includes doc comments normal comments file header comments etc.
Arguments
/comment-audit <file...> — audit exactly these files.
/comment-audit pick <n> — find the n most audit-worthy files (never audited first, then stale,
ranked by comment volume) and audit those.
With no arguments, ask whether the user wants specific files or a pick, and how many.
1. Choose the files
For explicit files, take them as given (they must be tracked by git). Otherwise:
node .claude/skills/comment-audit/ledger.mjs pick <n>
Output is JSON: each candidate's path, state (never | stale), rough commentLines, and
auditedAt where one exists. list [--all] shows the whole picture (--all includes clean
files). Candidates are tracked *.ts|tsx|js|mjs|css files outside vendor/, examples/,
docs/, templates/, and dist/.
Tell the user which files were chosen and why before editing anything.
2. Audit each file
Read the file in full. Judge every comment — doc and inline — against CLAUDE.md
### Comments. The substance rule is plain declarative prose, no epigrams; the patterns
to catch are listed there (inverted syntax and personification, metaphorical equations,
fragment openers that defer the subject, double negatives, pronouns and ellipses that point
outside the sentence). Also enforce the mechanical rules: // for non-doc comments, non-doc
comments at most 3 lines, doc comments concise, no leftover CLAUDENOTE:.
While auditing, also fix comments that are stale (describe code that changed), redundant
(restate the line below), or wrongly placed. Do not touch code — comment-only edits. A comment
that is already plain and informative is left alone; rewriting for taste is not the job.
If a comment encodes a decision you cannot verify, preserve the meaning exactly and only fix
the prose. When unsure what a comment means, say so in the report instead of guessing a
rewrite.
3. Verify
For each edited file, run the checks by name — never a blanket pnpm lint:
pnpm exec prettier --check <files>
pnpm exec eslint <files>
eslint doubles as a parse check that the edits did not break syntax. Comment-only edits cannot
change types or behaviour, so pnpm check and tests are not required — but if any edit strayed
beyond comments, run pnpm check too and say so.
4. Record
After the edits are in place (recording first would store a pre-edit blob hash and immediately
read as stale):
node .claude/skills/comment-audit/ledger.mjs record <file...>
Record every file that was audited, including files that needed no changes — a clean audit is
still an audit. The ledger is committed alongside the fixes; do not commit unless the user
asks, but when they do, the ledger change belongs in the same commit as the comment fixes.
5. Report
Summarize per file: how many comments were rewritten, one or two representative
before/after pairs, anything flagged rather than fixed, and the verification results. Note
that the ledger was updated and where it lives.
