From 83d879265e8a2ffbff2866c549cfcb7e15d3da66 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Sun, 26 Apr 2026 22:32:26 -0500
Subject: [PATCH] [core] Document add_then/add_else single-call precondition

---
 esphome/core/base_automation.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/esphome/core/base_automation.h b/esphome/core/base_automation.h
index 9418170b6d..afd11c6867 100644
--- a/esphome/core/base_automation.h
+++ b/esphome/core/base_automation.h
@@ -287,6 +287,10 @@ template<bool HasElse, typename... Ts> class IfAction : public Action<Ts...> {
  public:
   explicit IfAction(Condition<Ts...> *condition) : condition_(condition) {}
 
+  // Precondition: add_then/add_else must be called at most once per instance.
+  // Codegen always batches the full action list into a single call. Calling
+  // twice would re-append the same inline continuation pointer and form a
+  // self-loop in the next_ chain.
   void add_then(const std::initializer_list<Action<Ts...> *> &actions) {
     this->then_.add_actions(actions);
     this->then_.add_action(&this->then_continuation_);
@@ -336,6 +340,7 @@ template<typename... Ts> class WhileAction : public Action<Ts...> {
  public:
   WhileAction(Condition<Ts...> *condition) : condition_(condition) {}
 
+  // Precondition: must be called at most once per instance (see IfAction::add_then).
   void add_then(const std::initializer_list<Action<Ts...> *> &actions) {
     this->then_.add_actions(actions);
     this->then_.add_action(&this->loop_continuation_);
@@ -399,6 +404,7 @@ template<typename... Ts> class RepeatAction : public Action<Ts...> {
  public:
   TEMPLATABLE_VALUE(uint32_t, count)
 
+  // Precondition: must be called at most once per instance (see IfAction::add_then).
   void add_then(const std::initializer_list<Action<uint32_t, Ts...> *> &actions) {
     this->then_.add_actions(actions);
     this->then_.add_action(&this->loop_continuation_);