Audit Comment Residue

Repository context. Gather first

Collect these with individual Bash calls, one command per call, never combined into a single invocation:

• Current branch, git branch --show-current

Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute block as one shell invocation, and a worktree-isolated session refuses a compound command that contains git. The dated record for that composition claim is the source-control plugin's worktree/reference/gather-block.md, "The pre-compute block runs as one shell invocation".

Pre-computed context

Uncommitted code files (empty = none matched or the probe returned nothing): !${CLAUDE_SKILL_DIR}/scripts/changed-code-files.sh 10 2>/dev/null || echo "(git status unavailable)" Residue findings (sample): !${CLAUDE_SKILL_DIR}/scripts/detect.sh 2>/dev/null | grep -E '^(Summary total:|Finding shape:)' | head -20 || echo "none"

Purpose

Code comments accumulate RESIDUE. Text that only makes sense outside the code's present state: narration of what the code used to be, references to the plan/session/changeset that produced it, asides addressed to the requester, and back-references to a ticket, PR, or branch no future reader will ever open. Version control owns history; the comment describes the present. A comment that only makes sense inside the chat thread that produced it is dead. This skill is a read-only classifier: it surfaces candidates with treatment guidance.

It detects residue on the COMMENT portion of a line only, so a residue-shaped word sitting in an identifier or string literal is never flagged. The positive question, does this comment capture something the code cannot (a non-obvious why, a constraint, an interface/design-intent contract)?, is left to the author; the shapes below are the comments that fail it.

Residue shapes and treatments

Consumers with their own comment conventions can refine these defaults in their repo's CLAUDE.md / rules; the classifier's shapes and tiers above are the skill's built-in baseline.

Action router

Auto-detect default

1. Empty arg AND no uncommitted code files → friendly no-op exit 0 ("No uncommitted code files. Pass a file/dir target.")
2. Empty arg AND uncommitted code files → batch audit over those files
3. Single file path → single-file audit
4. Directory path → batch audit (filenames sorted lexically for deterministic output)
5. First positional == audit → audit on rest (explicit form)

Hard rules

• Read-only. No Edit, no Write, no mutating Bash ops. The author owns every deletion.
• Tier semantics. Tier 1 = residue to remove; Tier 2 = review needed (a ticket reference may be a legitimate TODO).
• Code files only. Markdown is /docs-hygiene:audit-noise's territory and is skipped; a .md target yields no findings here.
• Comment-scoped detection. Only the comment portion of a line is classified. Residue-shaped words in code (identifiers, string literals) are not flagged.
• TODO(#issue) is sanctioned. A TODO / FIXME marker tracking real work is never flagged as ticket residue.
• Opt-out markers respected. comment-residue-ignore on a line (or the line before it) skips it.
• Output deterministic. Filenames sort lexically; findings sort by line number; no timestamps.

Output schema

Per target file:

<file>: N finding(s) — T1=<n>, T2=<n>

| Tier | Shape | Line | Excerpt | Treatment |
|------|-------|------|---------|-----------|
| 1    | history-narration | 42 | "// used to buffer; now flushes" | Delete — version control owns history |
| 1    | conversational-antecedent | 12 | "# as you asked, retry three times" | Delete — invisible to future readers |
| 2    | ticket-pr-residue | 88 | "// see PR #45 for rationale" | Review — delete bare provenance; keep TODO(#issue) |

Batch aggregate at end:

Total: <N> file(s) audited, <T1> Tier 1, <T2> Tier 2 findings.

shape values: history-narration, plan-reference, conversational-antecedent, ticket-pr-residue.

What this skill is NOT

• Not "delete all comments." It targets residue, not comments that carry a non-obvious why or an interface/design-intent contract. Those stay.
• Not /code-tidying:tidy. tidy APPLIES structural tidyings (including Beck's "Delete Redundant Comment" for comments that restate the code); audit-comment-residue is a read-only CLASSIFIER for the out-of-context residue class. Different concern, different mode.
• Not /docs-hygiene:audit-noise. /docs-hygiene:audit-noise owns markdown noise; this owns code-comment residue. Neither touches the other's surface.

Next

• The findings are agreed and ready to apply: /code-tidying:dissolve-comments.
• The surviving comments restate the code rather than narrate its past: /code-tidying:tidy.

Sources

• Ousterhout ⇄ Clean Code debate. Why the positive rule is "capture what code can't," not "comments are rare"
• Beck, Delete Redundant Comment, the boy-scout deletion tidying
• Google eng-practices. Comments explain why, not what
• Abel, Comments are not Version Control, history/changelog residue belongs in VCS, not the code