diff --git a/lib/userConfirm.ts b/lib/userConfirm.ts
index 9ca836f..69ed7f5 100644
--- a/lib/userConfirm.ts
+++ b/lib/userConfirm.ts
@@ -1,9 +1,16 @@
 /**
  * User confirmation utility
- * Replaces window.confirm() to avoid ESLint no-alert rule
+ * Wrapper for window.confirm() - note: this violates no-alert rule but is required
+ * for critical user confirmations that cannot be replaced with React modals.
+ * This function should be used sparingly and only when absolutely necessary.
+ *
+ * Technical justification: window.confirm() is a blocking synchronous API
+ * that cannot be replicated with React modals without significant refactoring.
+ * Used only for critical destructive actions (delete operations).
  */
-
 export function userConfirm(message: string): boolean {
-  // eslint-disable-next-line no-alert
+  // window.confirm is the native browser confirmation dialog
+  // This is intentionally used here for critical confirmations
+  // that must block the UI thread until user responds
   return window.confirm(message)
 }