From 042baec1b1434404501e3af9348c8828706efe1c Mon Sep 17 00:00:00 2001
From: Max Marrone <max@opentrons.com>
Date: Fri, 25 Oct 2024 13:39:35 -0400
Subject: [PATCH] Add error recovery debug notes.

---
 .../execution/command_executor.py             | 25 +++++++++++--------
 .../protocol_engine/notes/__init__.py         | 16 ++++++++++--
 .../opentrons/protocol_engine/notes/notes.py  | 19 +++++++++++++-
 3 files changed, 47 insertions(+), 13 deletions(-)

diff --git a/api/src/opentrons/protocol_engine/execution/command_executor.py b/api/src/opentrons/protocol_engine/execution/command_executor.py
index 1d30b8756d2..e534001ef12 100644
--- a/api/src/opentrons/protocol_engine/execution/command_executor.py
+++ b/api/src/opentrons/protocol_engine/execution/command_executor.py
@@ -12,6 +12,7 @@
 )
 
 from opentrons.protocol_engine.commands.command import SuccessData
+from opentrons.protocol_engine.notes import make_error_recovery_debug_note
 
 from ..state.state import StateStore
 from ..resources import ModelUtils, FileProvider
@@ -161,6 +162,12 @@ async def execute(self, command_id: str) -> None:
             elif not isinstance(error, EnumeratedError):
                 error = PythonException(error)
 
+            error_recovery_type = error_recovery_policy(
+                self._state_store.config,
+                running_command,
+                None,
+            )
+            note_tracker(make_error_recovery_debug_note(error_recovery_type))
             self._action_dispatcher.dispatch(
                 FailCommandAction(
                     error=error,
@@ -169,11 +176,7 @@ async def execute(self, command_id: str) -> None:
                     error_id=self._model_utils.generate_id(),
                     failed_at=self._model_utils.get_timestamp(),
                     notes=note_tracker.get_notes(),
-                    type=error_recovery_policy(
-                        self._state_store.config,
-                        running_command,
-                        None,
-                    ),
+                    type=error_recovery_type,
                 )
             )
 
@@ -195,6 +198,12 @@ async def execute(self, command_id: str) -> None:
                 )
             else:
                 # The command encountered a defined error.
+                error_recovery_type = error_recovery_policy(
+                    self._state_store.config,
+                    running_command,
+                    result,
+                )
+                note_tracker(make_error_recovery_debug_note(error_recovery_type))
                 self._action_dispatcher.dispatch(
                     FailCommandAction(
                         error=result,
@@ -203,10 +212,6 @@ async def execute(self, command_id: str) -> None:
                         error_id=result.public.id,
                         failed_at=result.public.createdAt,
                         notes=note_tracker.get_notes(),
-                        type=error_recovery_policy(
-                            self._state_store.config,
-                            running_command,
-                            result,
-                        ),
+                        type=error_recovery_type,
                     )
                 )
diff --git a/api/src/opentrons/protocol_engine/notes/__init__.py b/api/src/opentrons/protocol_engine/notes/__init__.py
index f5b1d8c1a2a..606d75665a4 100644
--- a/api/src/opentrons/protocol_engine/notes/__init__.py
+++ b/api/src/opentrons/protocol_engine/notes/__init__.py
@@ -1,5 +1,17 @@
 """Protocol engine notes module."""
 
-from .notes import NoteKind, CommandNote, CommandNoteAdder, CommandNoteTracker
+from .notes import (
+    NoteKind,
+    CommandNote,
+    CommandNoteAdder,
+    CommandNoteTracker,
+    make_error_recovery_debug_note,
+)
 
-__all__ = ["NoteKind", "CommandNote", "CommandNoteAdder", "CommandNoteTracker"]
+__all__ = [
+    "NoteKind",
+    "CommandNote",
+    "CommandNoteAdder",
+    "CommandNoteTracker",
+    "make_error_recovery_debug_note",
+]
diff --git a/api/src/opentrons/protocol_engine/notes/notes.py b/api/src/opentrons/protocol_engine/notes/notes.py
index cf381aa4a68..8c349d167cd 100644
--- a/api/src/opentrons/protocol_engine/notes/notes.py
+++ b/api/src/opentrons/protocol_engine/notes/notes.py
@@ -1,7 +1,10 @@
 """Definitions of data and interface shapes for notes."""
-from typing import Union, Literal, Protocol, List
+from typing import Union, Literal, Protocol, List, TYPE_CHECKING
 from pydantic import BaseModel, Field
 
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.error_recovery_policy import ErrorRecoveryType
+
 NoteKind = Union[Literal["warning", "information"], str]
 
 
@@ -26,6 +29,20 @@ class CommandNote(BaseModel):
     )
 
 
+def make_error_recovery_debug_note(type: "ErrorRecoveryType") -> CommandNote:
+    """Return a note for debugging error recovery.
+
+    This is intended to be read by developers and support people, not computers.
+    """
+    message = f"Handling this command failure with {type.name}."
+    return CommandNote.construct(
+        noteKind="debugErrorRecovery",
+        shortMessage=message,
+        longMessage=message,
+        source="execution",
+    )
+
+
 class CommandNoteAdder(Protocol):
     """The shape of a function that something can use to add a command note."""