Say what a comment should do rather than what it shouldn't

- Turn the list of things never to describe into positive bullets.
- Fold in history of what was removed, and the dev journal, as belonging in the
  commit or PR description.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/agents/code-style.md

@@ -42,15 +42,12 @@ simplification.
 - Say the reason, then stop. Test each sentence: does the reason still stand
   without it? If so, cut it. Most reasons fit on a line, so a long comment is
   worth a second look — it is usually carrying something that isn't one.
-- Never describe:
+- Write about the line the comment sits on, in terms of what the code does
-  - layout or placement — the stylesheet says it, and changes without the
+  there — leave layout to the stylesheet and measurements to the design.
-    comment;
+- Name the condition ("where the platform can't route audio"), not the browser
-  - the context around the code — it moves without touching the line;
+  or the spec entry.
-  - design measurements — the design is the source;
+- Put history — what was tried, removed or rejected, the dev journal — in the
-  - how a decision was reached, or what was rejected — that goes in the PR body
+  commit or the PR description.
-    or the feature spec;
-  - what the next line does, or what an assertion checks.
-- No spec ids (D11, AC23) and no browser lists — both go stale silently.
 - In tests, comment only structure that looks wrong but isn't: batching, timers,
   why this scroll position.