why-commentslisted

Use when a file is littered with comments that narrate what the code already says (`// increment the counter`), when load-bearing code has no explanation of why it exists, or when reviewing AI-generated code (agents pad output with narration and never record the why). Deletes comments that restate the code, keeps and sharpens the ones that capture a non-obvious why — the workaround, the spec quirk, the ordering constraint — and adds a why where surprising code has none. Use when you hit a line that makes you ask 'why on earth is this here?' and the comment above it just says what it does.
mikestangdevs/craft-skills · ★ 2 · Code & Development · score 75

Install: claude install-skill mikestangdevs/craft-skills

# Why Comments ## The failure mode this fixes Comments fail in two opposite directions. Agents (and tired humans) write narration — `// loop over the users`, `// call the API` — that restates what the code already says, goes stale the moment the code changes, and trains every reader to skip comments entirely. Meanwhile the *one* thing a comment can do that code can't — record **why** — goes unwritten: why the retry is 3 and not 5, why this runs before that, why the obvious approach was tried and reverted. Six months later someone "simplifies" the workaround and reintroduces the bug it guarded against. This skill inverts the ratio: delete the *whats*, keep and sharpen the *whys*, and add a why where surprising code has none. ## When to Use This Skill - A file is full of comments that just narrate the next line - Load-bearing or surprising code (a magic value, an odd ordering, a deliberately "wrong-looking" approach) has no explanation - You're reviewing AI-generated code — agents over-narrate and under-justify - `explain-back` flagged a chunk `UNJUSTIFIED` and the justification, once found, should be written down - A comment and the code beneath it disagree (the comment went stale) **Don't use when:** the comments are API documentation (docstrings, JSDoc, godoc) — those describe a contract for consumers and are a different job, judged by different rules. And don't add a why where the code is genuinely self-evident; a comment on the obvious is noise wearing a justificatio