# 3 · Comment: write what a person can act on The author reads your comments one at a time, often between other work. Each one has to answer three questions on its own: how much does this matter, what exactly is wrong, and what should I do. A comment that leaves any of those open turns into a conversation, and a review that should take an hour takes three days. On a small change: label each comment (W1) and make each one actionable (W2). The rest applies when there are more than a handful. --- ### W1 · Label every comment with how much it matters **Rule:** Start every comment with one of four labels, and use them consistently: - **Blocking:** must change before this merges. Lost or exposed data, a security hole, wrong results, a broken caller, a failing test, or the change doesn't do what the ticket asks. - **Should fix:** a real problem, but the author may reasonably choose to fix it in a follow-up: a missing edge case that's unlikely, a confusing name for an important thing, a duplicated helper. - **Nit:** a small preference. Fine to ignore. Never blocks. - **Question:** you don't understand something and need to before you can judge it. Not a request for change, though the answer may lead to one. If the project already uses its own labels (`nit:`, `blocker:`, Conventional Comments, emoji), use those instead. **Why:** Without labels, every comment looks equally urgent. The author either treats them all as blocking and spends a day on spacing, or treats them all as optional and skips the one that loses data. The label is what lets them plan. **Agent trap:** twelve unlabelled comments where "consider extracting this into a helper" reads with the same weight as "this deletes every row when `status` is empty". Or labelling something "blocking" because you'd do it differently. **Check:** every comment starts with a label. Each "blocking" one names the harm (D2 questions 1 to 5) or the project rule it breaks. If more than half your comments are nits, cut most of them (W6). ### W2 · Say where, what, why, and a fix **Rule:** Put each comment on the exact line, or on the smallest range of lines it's about. In it, say what the problem is, why it matters (what happens to whom), and what to do about it: a suggested fix in a few lines, or a description of one if it's bigger. Use the review tool's suggestion feature for small fixes, so the author can accept it in one click. Write about the code, not the author: "this skips the last item", not "you forgot the last item". **Why:** "This seems off" sends the author looking for what you saw, and they may fix the wrong thing. A comment with the place, the reason and a fix takes a minute to act on. The reason also lets them disagree with evidence, which is how reviews get things right. **Agent trap:** a comment on line 1 of the file that says "error handling could be improved here". Which error? Which line? Improved how? Or the opposite: a fix with no reason, so the author applies it without knowing what it fixed, and makes the same mistake in the next file. **Check:** read each comment as the author, with only that comment and the line it's on. Can they act without asking you anything? Use this shape: ``` [Blocking] `deleteMany({ status })` runs with `status` undefined when the filter is cleared (Basket.tsx line 88 sends `undefined`), which deletes every order. Suggest: return early if `status` is missing, and add a test for the cleared filter. if (!status) throw new Error("status is required"); ``` > **In ihumane Pro** (https://ihumane.ai/#pricing): > - W3 · Sound as sure as you are, and say why > - W4 · Review the change; don't rewrite it > - W5 · Ask when you don't know why > - W6 · Say a repeated problem once > - W7 · Say what's good, briefly and specifically