AGENTS.md additions

AGENTS.md

@@ -390,12 +390,32 @@ Avoid phrasings like:
 - "cleaner than the previous approach"
 - "we used to ... but ..."
 - "after trying X, we found Y"
+- "X rather than Y", where Y is what the code did before the change
 
 The iteration story is sometimes worth preserving — but it belongs in the
 commit message, which is the durable record of *why this change was made*. The
 code comment should make sense to someone who has never seen any prior version
 and is just trying to understand the file as it currently exists.
 
+The tell is subtler than an explicit "we used to". A comment that justifies the
+code against an alternative — "run it on a worker rather than blocking the UI",
+"switch panels in `Then` rather than a moment earlier" — is history in disguise
+whenever that alternative is what the code did before the change. It reads as
+ordinary rationale, but the reader has no way to know the contrast is with a
+version that no longer exists.
+
+So the check to apply is: would you have written this comment if you were
+writing the file from scratch, with no diff in mind? If not, the sentence
+belongs in the commit message.
+
+## Don't justify routine call sites
+
+If the codebase calls a helper in twenty places without explanation, your
+twenty-first call site doesn't need one either. A comment there says "something
+here is unusual"; when nothing is, it's noise — and it invites exactly the kind
+of before/after justification the section above warns about. Look at the
+neighboring call sites before writing one: if they're bare, match them.
+
 ## Don't present "live with the bug" as an option
 
 When you're investigating a defect and laying out fix options for the user,