Merge pull request #98062 from Expensify/marcaaron-remove-claudeisms

Remove AI-generated jargon from comments [No QA]

Author: marcaaron

.claude/skills/coding-standards/SKILL.md

@@ -55,6 +55,7 @@ Coding standards for the Expensify App. Each standard is a standalone file in `r
 - [CONSISTENCY-14](rules/consistency-14-new-file-header.md) — Non-trivial new files start with a header description
 - [CONSISTENCY-15](rules/consistency-15-comment-why.md) — Comments explain why the code exists, not what it does
 - [CONSISTENCY-16](rules/consistency-16-plain-comment-style.md) — Write comments as plain, natural sentences
+- [CONSISTENCY-17](rules/consistency-17-no-ai-jargon.md) — No AI-generated jargon in code or comments
 
 ### Clean React Patterns
 - [CLEAN-REACT-PATTERNS-0](rules/clean-react-0-compiler.md) — React Compiler compliance

.claude/skills/coding-standards/rules/consistency-17-no-ai-jargon.md

@@ -0,0 +1,56 @@
+---
+ruleId: CONSISTENCY-17
+title: No AI-generated jargon in code or comments
+---
+
+## [CONSISTENCY-17] No AI-generated jargon in code or comments
+
+### Reasoning
+
+Certain phrases appear constantly in AI-generated code but rarely in code written by engineers. They make the codebase sound like it was written by a chatbot and should be replaced with plain, direct language.
+
+### Banned phrases
+
+| Phrase | Plain substitute |
+|--------|-----------------|
+| sentinel | placeholder, marker, guard entry |
+| fan out | send, make, dispatch, distribute |
+| carve out | set aside, exclude, separate |
+| defense in depth | extra guard, additional check |
+| belt and suspenders / belt-and-suspenders | extra safety check, redundant guard |
+| fresh evidence | new data, updated result |
+
+### Incorrect
+
+```ts
+// Fan out the request to every matching snapshot.
+function getSentinelValue() { ... }
+const fanOutRequests = () => { ... }
+
+// Defense in depth: reject the value if it arrived stale.
+// Belt-and-suspenders check before writing.
+// Uses a sentinel to signal end-of-stream.
+```
+
+### Correct
+
+```ts
+// Send the request to every matching snapshot.
+function getPlaceholderValue() { ... }
+const sendDuplicateRequests = () => { ... }
+
+// Additional guard: reject the value if it arrived stale.
+// Extra safety check before writing.
+// Uses a placeholder to signal end-of-stream.
+```
+
+---
+
+### Review Metadata
+
+Flag when any added or modified code — including comments, function names, variable names, type names, or string literals — contains one of the banned phrases above.
+
+**DO NOT flag if:**
+
+- The phrase appears inside a quoted external API name, a third-party library identifier, or a value the codebase does not control (e.g. a server response field name)
+- The phrase is in a test description string that is directly testing behavior described by an external spec or API that uses the term

src/components/ConnectToHRFlow/index.ios.tsx

@@ -40,7 +40,7 @@ function ConnectToHRFlow({setupLink, onDone}: ConnectToHRFlowProps) {
         hasOpened.current = true;
 
         getShortLivedAuthTokenURL(setupLink)
-            // CONST.DEEPLINK_BASE_URL is used as a sentinel so ASWebAuthenticationSession
+            // CONST.DEEPLINK_BASE_URL is used as the redirect URL so ASWebAuthenticationSession
             // auto-dismisses when the flow redirects back to the app via deep link.
             .then((url) => {
                 if (isDismissed.current) {

src/components/Modal/useSyncModalWithHistory/index.ts

@@ -26,17 +26,17 @@ type UseSyncModalWithHistoryParams = {
 };
 
 /**
- * Web: represents a `shouldHandleNavigationBack` modal's back-guard as a uniquely-tagged sentinel in the
+ * Web: represents a `shouldHandleNavigationBack` modal's back-guard as a uniquely-tagged history entry in the
  * root navigator's `state.history` (dispatched via `TOGGLE_MODAL_WITH_HISTORY`). React Navigation's
  * `useLinking` mirrors the history length delta into the browser, so opening the modal pushes a browser
- * entry and browser Back removes it. The router consumes the sentinel on forward navigation
+ * entry and browser Back removes it. The router consumes the guard entry on forward navigation
  * (history length unchanged → `replaceState`) so no orphaned entry is left behind.
  *
  * The per-instance tag lets nested modals add/remove their own guard independently (LIFO).
  */
 export default function useSyncModalWithHistory({isVisible, shouldHandleNavigationBack, onClose, onOpen}: UseSyncModalWithHistoryParams) {
     const modalId = useId();
-    const sentinel = `${CONST.NAVIGATION.CUSTOM_HISTORY_ENTRY_MODAL}:${modalId}`;
+    const guardEntry = `${CONST.NAVIGATION.CUSTOM_HISTORY_ENTRY_MODAL}:${modalId}`;
 
     const guardStateRef = useRef<ModalGuardState>(MODAL_GUARD_STATE.CLOSED);
 
@@ -50,7 +50,7 @@ export default function useSyncModalWithHistory({isVisible, shouldHandleNavigati
 
     const snapshotKey = useSyncExternalStore(
         subscribeToRootNavigation,
-        () => getModalGuardSnapshotKey(sentinel),
+        () => getModalGuardSnapshotKey(guardEntry),
         () => EMPTY_MODAL_GUARD_SNAPSHOT_KEY,
     );
     // We can't use usePrevious here because we need to imperatively reset this ref mid-effect
@@ -89,7 +89,7 @@ export default function useSyncModalWithHistory({isVisible, shouldHandleNavigati
         }
         guardStateRef.current = MODAL_GUARD_STATE.CLOSING_BY_DISPATCH;
         // Defer (microtask via isNavigationReady) so any forward navigation fired from the same close
-        // handler is dispatched first; the router then consumes our sentinel during that push and this
+        // handler is dispatched first; the router then consumes our guard entry during that push and this
         // toggle(false) becomes a no-op, avoiding an extra browser back().
         Navigation.isNavigationReady().then(() => {
             navigationRef.dispatch({
@@ -99,7 +99,7 @@ export default function useSyncModalWithHistory({isVisible, shouldHandleNavigati
         });
     }, [isVisible, shouldHandleNavigationBack, modalId]);
 
-    // Browser Back/Forward changes the guard sentinel in root history — react via snapshot transitions.
+    // Browser Back/Forward changes the guard entry in root history, so we react via snapshot transitions.
     useEffect(() => {
         if (!shouldHandleNavigationBack) {
             prevSnapshotKeyRef.current = snapshotKey;

src/components/Modal/useSyncModalWithHistory/modalGuardSnapshot.ts

@@ -13,14 +13,14 @@ const EMPTY_MODAL_GUARD_SNAPSHOT: ModalGuardSnapshot = {
 
 const EMPTY_MODAL_GUARD_SNAPSHOT_KEY = 'false:0';
 
-function getModalGuardSnapshot(sentinel: string): ModalGuardSnapshot {
+function getModalGuardSnapshot(guardEntry: string): ModalGuardSnapshot {
     if (!navigationRef.isReady()) {
         return EMPTY_MODAL_GUARD_SNAPSHOT;
     }
 
     const state = navigationRef.getRootState();
     return {
-        guardPresent: !!state?.history?.includes(sentinel),
+        guardPresent: !!state?.history?.includes(guardEntry),
         routesLength: state?.routes?.length ?? 0,
     };
 }
@@ -29,8 +29,8 @@ function serializeModalGuardSnapshot(snapshot: ModalGuardSnapshot): string {
     return `${snapshot.guardPresent}:${snapshot.routesLength}`;
 }
 
-function getModalGuardSnapshotKey(sentinel: string): string {
-    return serializeModalGuardSnapshot(getModalGuardSnapshot(sentinel));
+function getModalGuardSnapshotKey(guardEntry: string): string {
+    return serializeModalGuardSnapshot(getModalGuardSnapshot(guardEntry));
 }
 
 function parseModalGuardSnapshotKey(snapshotKey: string): ModalGuardSnapshot {

src/components/Modal/useSyncModalWithHistory/modalGuardState.ts

@@ -17,27 +17,27 @@ const MODAL_GUARD_EFFECT = {
 } as const;
 
 /**
- * Lifecycle of one modal's browser-history back-guard sentinel. A single state replaces the previous
+ * Lifecycle of one modal's browser-history back-guard entry. A single state replaces the previous
  * pair of correlated booleans (`hasGuard` / `isClosingByDispatch`) so the invalid "registered AND
  * closing" combination cannot be expressed.
  *
- * - `CLOSED`: no sentinel registered.
- * - `OPEN`: sentinel registered; browser Back removes it.
- * - `CLOSING_BY_DISPATCH`: we initiated the close and removed our own sentinel, so the resulting
+ * - `CLOSED`: no guard registered.
+ * - `OPEN`: guard registered; browser Back removes it.
+ * - `CLOSING_BY_DISPATCH`: we initiated the close and removed our own guard entry, so the resulting
  *   `GUARD_REMOVED` must be swallowed rather than treated as a browser Back.
  */
 type ModalGuardState = (typeof MODAL_GUARD_STATE)[keyof typeof MODAL_GUARD_STATE];
 
 type ModalGuardEvent =
     | {
-          /** Our sentinel left root history (browser Back, our own close, or forward-nav consume). */
+          /** Our guard entry left root history (browser Back, our own close, or forward-nav consume). */
           type: typeof MODAL_GUARD_EVENT_TYPE.GUARD_REMOVED;
 
           /** Whether a route was pushed alongside the removal (forward navigation consumed the guard). */
           routesGrew: boolean;
       }
     | {
-          /** Our sentinel re-entered root history (browser Forward restored the saved nav state). */
+          /** Our guard entry re-entered root history (browser Forward restored the saved nav state). */
           type: typeof MODAL_GUARD_EVENT_TYPE.GUARD_APPEARED;
       };
 
@@ -50,12 +50,12 @@ type ModalGuardTransition = {
 /**
  * Pure transition for a modal's back-guard in response to root-history changes. The write path sets
  * `OPEN` / `CLOSING_BY_DISPATCH` directly; this reducer owns the ambiguous external events where one
- * observable change (the sentinel disappearing) has several possible causes.
+ * observable change (the guard entry disappearing) has several possible causes.
  */
 function reduceModalGuardState(state: ModalGuardState, event: ModalGuardEvent, isVisible: boolean): ModalGuardTransition {
     switch (event.type) {
         case MODAL_GUARD_EVENT_TYPE.GUARD_REMOVED:
-            // Our own close dispatch removed the sentinel — settle without firing onClose.
+            // Our own close dispatch removed the guard entry, so settle without firing onClose.
             if (state === MODAL_GUARD_STATE.CLOSING_BY_DISPATCH) {
                 return {state: MODAL_GUARD_STATE.CLOSED};
             }

src/components/MoneyRequestConfirmationList/hooks/useConfirmationValidation.ts

@@ -239,7 +239,7 @@ function useConfirmationValidation({
 
         const isCategoryBeingCreated = policyCategories?.[iouCategory]?.pendingAction === CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD;
 
-        // The 'Uncategorized'/'none' sentinel means no category, so treat it as missing (not out of policy) here, mirroring
+        // The 'Uncategorized'/'none' placeholder means no category, so treat it as missing (not out of policy) here, mirroring
         // isCategoryMissing/ViolationsUtils. Otherwise it wrongly blocks confirmation when the policy lacks that literal category.
         if (iouCategory && !isCategoryMissing(iouCategory) && policyCategories && !policyCategories[iouCategory]?.enabled && !isCategoryBeingCreated) {
             return {errorKey: 'violations.categoryOutOfPolicy'};

src/components/Popover/index.tsx

@@ -67,7 +67,7 @@ function Popover(props: PopoverProps) {
         // changes, without intercepting that navigation.
         //
         // We subscribe to React Navigation state events rather than raw `popstate` so that
-        // `navigationRef.getCurrentRoute()` is already fresh when the callback fires. Sentinel-only
+        // `navigationRef.getCurrentRoute()` is already fresh when the callback fires. History changes from guard entries only
         // history changes (e.g. a nested YearPickerModal opening/closing) do NOT change the focused
         // route key, so the calendar popover stays open. A real navigation away changes the key and
         // closes the popover.

src/components/Search/SearchRouter/SearchRouterContext.tsx

@@ -56,8 +56,8 @@ function SearchRouterContextProvider({children}: ChildrenProps) {
     const searchRouterDisplayedRef = useRef(false);
 
     // Registers a browser-history entry when the SearchRouter is open, so browser Back closes it
-    // and browser Forward (after Back) reopens it. Uses the same sentinel mechanism as other modals
-    // rather than direct window.history calls, avoiding misalignment with other sentinel-tracked overlays.
+    // and browser Forward (after Back) reopens it. Uses the same back-guard mechanism as other modals
+    // rather than direct window.history calls, avoiding misalignment with other guard-tracked overlays.
     useSyncModalWithHistory({
         isVisible: isSearchRouterDisplayed,
         shouldHandleNavigationBack: true,

src/libs/Navigation/AppNavigator/createRootStackNavigator/GetStateForActionHandlers.ts

@@ -627,11 +627,11 @@ function handleToggleModalWithHistoryAction(state: StackNavigationState<ParamLis
         return state;
     }
 
-    // Each modal instance owns a uniquely-tagged sentinel so nested modals can be added/removed
-    // independently (LIFO), unlike the singleton side-panel sentinel.
+    // Each modal instance owns a uniquely-tagged history entry so nested modals can be added/removed
+    // independently (LIFO), unlike the singleton side-panel entry.
     const entry = `${CONST.NAVIGATION.CUSTOM_HISTORY_ENTRY_MODAL}:${action.payload.modalId}`;
 
-    // On open, append this modal's back-guard sentinel. useLinking sees history grow by one and
+    // On open, append this modal's back-guard entry. useLinking sees history grow by one and
     // pushes a browser history entry, so browser Back closes the modal.
     // Skip if already present (e.g. browser Forward restored the saved nav state before our dispatch ran).
     if (action.payload.isVisible) {
@@ -641,8 +641,8 @@ function handleToggleModalWithHistoryAction(state: StackNavigationState<ParamLis
         return {...state, history: [...state.history, entry]};
     }
 
-    // On close, remove only this modal's own sentinel (the last matching one). Filtering by exact
-    // tag keeps sibling/nested modal sentinels intact.
+    // On close, remove only this modal's own entry (the last matching one). Filtering by exact
+    // tag keeps sibling/nested modal entries intact.
     const indexToRemove = state.history.lastIndexOf(entry);
     if (indexToRemove === -1) {
         return state;