claude-code-plugins

Pre-computed context

Current branch: !git branch --show-current 2>/dev/null || echo "unknown"
Uncommitted code files: !git status --porcelain 2>/dev/null | awk '{print $NF}' | grep -Ei '\.(cs|ts|tsx|js|jsx|py|sh|ps1|go|rs|java|rb|lua|sql|c|h|cpp|hpp|yaml|yml|toml)$' | head -10 || echo "none"
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; the author hand-applies every deletion.

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.
• Not an Edit operation. Read-only: it surfaces findings; the author applies deletions.

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