comment-cleanuplisted

Aggressively audit code comments against the user's strict "comments explain non-obvious why, never narrate what the code does" standard: delete comments that do not earn their place and compress the survivors (two-line ceiling, one line preferred). Use this whenever the user asks to review, audit, clean up, sanity-check, or justify comments; whenever they ask "did I follow the comment rules / our comment guidelines"; right after writing or heavily editing code; and before committing or opening a PR. Also use it proactively when you have just generated more than a couple of comments. The caller may restrict the audit to a path, a function/symbol, a glob, "staged", "the branch diff", or "the PR"; if no scope is given, audit only newly written or changed code, never the whole repo.
pricklywiggles/fractally-claude-marketplace · ★ 0 · Code & Development · score 62

Install: claude install-skill pricklywiggles/fractally-claude-marketplace

# Comment cleanup One idea drives this skill: **a comment must earn its place by saying something the code cannot, in as few words as possible.** Comments are read far more often than written, are never type-checked, and rot silently. A comment that restates the code is worse than none: the reader must read it, distrust it, and verify it against the code. The default verdict is REMOVE. A comment survives only by proving it carries information the code cannot express, and even then it gets compressed. A wrongly deleted comment costs one git revert; a wrongly kept one costs every future reader. When torn between KEEP and TRIM, trim. When torn between TRIM and REMOVE, remove. ## What survives Only a non-obvious *why* the code cannot be made to express: - **Business / domain rule** not derivable from the code ("archived rows excluded: the exporter counts them separately"). - **Edge case or workaround** ("WKWebView fires this twice on macOS; second ignored"). - **Historical / architectural decision** ("Rust, not config: a runtime env var can't drive a compile-time feature"). - **Cross-file or security intent** invisible locally ("pairs with the Rust devtools(false) gate; this only removes the in-app entry point"). - **Performance rationale** for code that would otherwise look arbitrary ("hoisted out of the row so the memoized child stays stable"). - **Tried-and-rejected alternative**, so it isn't "fixed" back ("red tint is invisible on this surface; signal is the