Comments — What Claude Gets Wrong

You over-comment. Your most common failure is adding comments that restate what the code already says. Your second most common failure is missing comments where they'd actually help. This skill fixes both.

The Litmus Test

"Does this comment tell the reader something they cannot determine from the code alone?"

If no, delete it. If yes, make it one sentence.

Comment Value Hierarchy (highest to lowest)

1. Why not — rejected alternatives, constraints that prevent the "obvious" approach
2. Why — reasoning, intent, business rules not obvious from domain names
3. Beware — concurrency hazards, non-obvious coupling, "here be dragons"
4. Context — links to bugs, specs, RFCs, issues, external docs
5. What — only for regex, bitwise ops, complex algorithms
6. How — almost never needed. The code IS the how.