@@ -86,6 +86,38 @@ def __init__(self, old: str, new: str) -> None:
8686class ReviewManagerNotNotifiedError (CoLRevException ):
8787 """
8888 The ReviewManager was not notified about the operation.
89+
90+ ``Dataset.load_records_dict()`` refuses to return data until the review
91+ manager knows which operation is about to run. It expects the
92+ :class:`~colrev.review_manager.ReviewManager` to have its
93+ ``notified_next_operation`` flag set, otherwise it raises this exception.
94+ Creating an operation immediately calls :meth:`Operation.notify()
95+ <colrev.operation.Operation.notify>` which sets that flag and runs the
96+ operation's precondition checks. In other words, you do *not* need to call
97+ ``notify()`` manually; instantiating the desired operation is enough.
98+
99+ The notification gate exists to prevent two classes of errors:
100+
101+ * **Dirty working tree issues** –
102+ :meth:`Operation.check_precondition()
103+ <colrev.operation.Operation.check_precondition>` ensures the repository is
104+ clean before state-changing work begins. It raises
105+ :class:`~colrev.exceptions.UnstagedGitChangesError` when modifications are
106+ unstaged and :class:`~colrev.exceptions.CleanRepoRequiredError` when tracked
107+ files outside the ignore list would be overwritten. By forcing dataset
108+ access to go through an operation, these safeguards always execute before
109+ records are read or written.
110+ * **Process-order violations** – the same precondition routine verifies that
111+ the requested operation is valid given each record's current status. It can
112+ raise :class:`~colrev.exceptions.ProcessOrderViolation` if earlier steps are
113+ missing or :class:`~colrev.exceptions.NoRecordsError` if work other than
114+ loading is attempted before any records exist. Requiring notification makes
115+ sure these workflow errors are caught instead of letting scripts bypass the
116+ process model.
117+
118+ ``ReviewManagerNotNotifiedError`` therefore ensures that every dataset access
119+ is routed through an operation, keeping the repository cleanliness and
120+ process-order checks in place.
89121 """
90122
91123 def __init__ (self ) -> None :
0 commit comments