audit-comment-residue

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): !bash "${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.