Keep shared state filters as forwarders; when is for one-off tests

AGENTS.md

@@ -395,7 +395,7 @@ file does, and it is the authority when they disagree. The most useful starting
 
     *   **Triggers -- Callback method (preferred):**
 
-        Use `build_callback_automation()` for simple triggers. This eliminates the need for a C++ Trigger class by using a lightweight pointer-sized forwarder struct registered directly as a callback. No `CONF_TRIGGER_ID` in the schema.
+        Use `build_callback_automation()` for simple triggers. The automation is registered directly as a callback on the parent, so there is no C++ Trigger class and nothing is allocated. No `CONF_TRIGGER_ID` in the schema.
 
         **Python:**
         ```python
@@ -448,6 +448,24 @@ file does, and it is the authority when they disagree. The most useful starting
             forward=[cg.StringRef(parent.option_at(index)), index],
         )
         ```
+
+        **Choosing the filter:** a filter that many automations share, such as entering one value of a state enum,
+        is a small forwarder struct templated on that value. Every automation for that value then shares one
+        function and passes only its `Automation *`. `when` generates a separate lambda per automation, which cost
+        16 to 64 bytes more flash when lock, media_player, alarm_control_panel and fusb302b were tried with it.
+        ```cpp
+        template<LockState State> struct LockStateForwarder {
+          Automation<> *automation;
+          void operator()(LockState state) const {
+            if (state == State)
+              this->automation->trigger();
+          }
+        };
+        ```
+        Use `when` for a test that is not a fixed value shared across automations, e.g. one that reads the parent:
+        `when="{parent}->is_fully_open()"` (valve). Only a trigger that must remember something between calls
+        (the last position, a click count) keeps a Trigger class.
+
         `build_parent_callback_automation`, `build_trigger_callback`, `build_callback_automations` and
         `build_trigger_automations` cover the other shapes; see their docstrings in `esphome/automation.py`.