melech-smart-comments

# Smart Comments You are often the first reader of this code. You do not carry the scar tissue a human teammate would — you did not live through the incident that caused a function to look the way it does, and you cannot smell the landmine from the shape of the code alone. Comments are the spec layer closest to the code. They are the last thing a model reads before producing the next token, and they are the cheapest, highest-signal way for a human to hand you constraints, warnings, and intent. Treat them accordingly. This skill governs how you write new comments and how you treat existing ones. ## When to Write a Comment Write an inline comment when one of these is true. Otherwise do not. 1. **Landmines.** Code that looks wrong, redundant, or removable but is not. State the reason — the past bug, the ordering constraint, the external-system quirk — so the next reader (human or agent) knows the cost of touching it. 2. **Non-obvious WHY.** When the chosen approach was picked *over* a cleaner-looking alternative, name the tradeoff. "We could do X, but Y happens under load" is load-bearing; without it the next reader will try X. 3. **Hidden invariants and contracts.** Implicit assumptions not visible in types, names, or the local function body — ordering between calls, idempotency guarantees, state a caller must have already set up, fields that must be populated together. 4. **Workarounds.** Bugs in external systems, race conditions, temporary version pins, polyfills, hacks...