paulrberg/audit-stale-comments

Audit Stale Comments

Audit source comments against the code they describe. Report only confirmed mismatches and noise; do not edit files unless the user separately asks for fixes.

Scope

Accept zero or more file or directory paths. With no arguments, use the current repository root. Resolve every path from the current working directory and report any path that cannot be read.

Discover JavaScript, JSX, TypeScript, TSX, and Go source files. By default exclude:

• tests, testdata, fixtures, snapshots, and stories;
• generated, vendor, dependency, coverage, cache, and build-output directories;
• minified JavaScript and generated Go files.

An explicitly named test file or test directory overrides only the test exclusion. Generated, vendored, minified, and build-output files remain excluded unless the user explicitly requests them.

Use repository-aware discovery when available (git ls-files or rg --files) and preserve the user's path order. Do not impose an arbitrary result cap.

Analysis

Split discovered files into non-overlapping batches of about ten. Delegate independent batches to read-only subagents when supported; otherwise inspect them directly. Continue useful work while delegated batches run.

For every line, block, and documentation comment, compare the claim with adjacent code, referenced symbols, callers, configuration, and relevant repository history when current code alone is inconclusive. Classify only clear findings:

• STALE: describes behavior the code no longer has;
• ORPHANED: references a symbol, path, flag, or concept that no longer exists;
• MISLEADING: materially suggests behavior different from the implementation;
• REDUNDANT: merely narrates self-explanatory code and carries no intent, constraint, or context.

Do not report style preferences, imperfect wording, useful rationale, or uncertainty as findings.

Behavior-Bearing Go Comments

Treat these as part of program behavior or required documentation, not ordinary prose:

• compiler and tool directives, including //go:*, //line, and //nolint;
• build constraints and their required placement;
• cgo preambles attached to import "C";
• go:embed patterns and the declarations they populate;
• package comments and exported-symbol documentation;
• concurrency, ownership, locking, lifetime, and safety contracts.

Verify these against Go syntax, symbol use, and tooling semantics. Never mark one redundant merely because the adjacent declaration is obvious.

Verification

Aggregate and deduplicate candidate findings, then reopen every reported location. Confirm its current line number and the implementation evidence that makes the comment wrong or unnecessary. Drop findings that cannot be verified. A clean result is valid and should not be padded with low-confidence observations.

Report

Return:

### 🔎 Stale-comments audit — <finding count or clean>

| Scope   | Files analyzed | Confirmed | Not reviewed    |
| ------- | -------------- | --------- | --------------- |
| <paths> | <count>        | <count>   | <count or none> |

### Findings

#### STALE

- path/to/file.ts:42 — <comment claim, contradictory evidence, and why it matters>

#### ORPHANED

#### MISLEADING

#### REDUNDANT

### ⚠️ Not reviewed

- <path and reason>

Omit empty category and not-reviewed sections. When no findings remain and every file was reviewed, lead with ### ✅ Clean — no confirmed stale, orphaned, misleading, or redundant comments. If files were not reviewed, lead with ### ⚠️ Review incomplete — no confirmed findings in reviewed scope instead. When fixes were requested and applied, lead with ### ✅ Comments fixed — <count>, then add ### 📦 Changed and ### 🧪 Verification; do not collapse a write receipt into Clean. Keep classifier tokens, paths, line numbers, directives, and quoted comment text exact and undecorated. Completion requires the exact scope, analyzed-file count, confirmed findings with current lines and evidence, and any files that could not be reviewed.