@clipboard-health/ai-rules 2.8.6 → 2.9.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clipboard-health/ai-rules",
   "description": "Pre-built AI agent rules for consistent coding standards.",
-  "version": "2.8.6",
+  "version": "2.9.1",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "keywords": [
     "ai",

package/rules/common/typeScript.md

@@ -94,9 +94,26 @@ throw new ServiceError({
 
 - Use `@clipboard-health/date-time` for all user-facing date formatting and all timezone-dependent operations (start-of-day-in-timezone, business hours, `setHours`, etc.) with an explicit `timeZone` parameter
 - Use `date-fns` only for timezone-agnostic timestamp math and parsing
+- Use `date-fns` comparison functions (`isBefore`, `isAfter`, `isEqual`, `isSameDay`, `compareAsc`, `compareDesc`) for all date comparisons — never use raw JS comparison operators (`>`, `<`, `===`, `>=`, `<=`) or `.getTime()` for equality/inequality checks
 - Never import `date-fns-tz`, `@date-fns/tz`, `moment`, or `moment-timezone`
 - In contracts, use `dateTimeSchema()` from `contract-core` for date fields — not `z.coerce.date()`, `z.string().datetime()`, or `z.date()`
 
+```typescript
+import { isBefore, isAfter, isSameDay } from "date-fns";
+
+// ✅ Good — explicit, readable, handles edge cases
+if (isBefore(shiftStart, now)) {
+}
+if (isSameDay(createdAt, today)) {
+}
+
+// ❌ Bad — raw JS comparison, implicit coercion risks
+if (shiftStart < now) {
+}
+if (shiftStart.getTime() === today.getTime()) {
+}
+```
+
 ## Internal Libraries
 
 - Use object arguments and object return types in library APIs; wrap exported responses in `ServiceResult`; prefer `ServiceResult` for expected errors and reserve throwing for unexpected/unrecoverable failures

package/rules/frontend/e2eTesting.md

@@ -25,6 +25,14 @@ await expect(page.getByText("Submit")).toBeVisible();
 await expect(page.getByText("Submit")).toBeAttached();
 ```
 
+## E2E vs Component Test Decision
+
+Before adding an E2E test:
+
+1. Check if existing E2E tests already cover the API calls and flows being tested — avoid duplicating coverage
+2. Confirm the flow is a core user journey (auth, payments, onboarding, multi-page navigation) — non-core flows belong in component tests even if they call backend APIs or touch API contracts
+3. Verify the test requires real cross-service integration or multi-page navigation — if it can be asserted with `render()` + `screen.getByRole()` or mocked API responses, write a component test instead
+
 ## Avoid
 
 - Hard-coded timeouts (`page.waitForTimeout`)

package/rules/frontend/reactComponents.md

@@ -86,3 +86,13 @@ return <Input onChange={(e) => setValue(e.target.value)} />;
 const handleSave = useCallback(async () => { ... }, [deps]);
 return <MemoizedChild onSave={handleSave} />;
 ```
+
+## Component Reuse
+
+Before creating a new component, search for existing ones in this order:
+
+1. **Shared UI libraries**: `@clipboard-health/ui-components`, `@clipboard-health/ui-react`, MUI
+2. **App-level shared directories**: e.g., `src/appV2/lib/`, `src/lib/components/`, `src/shared/`
+3. **Sibling features**: search for `*Card`, `*Modal`, `*Form`, `*EmptyState`, `*Page` patterns in other features
+
+If an existing component covers >70% of the need, extend it (prefer composition over boolean flags). Only create a new component when behavior is fundamentally different — document why in the PR.

package/skills/unresolved-pr-comments/SKILL.md

@@ -32,20 +32,16 @@ Then, for EVERY comment (both `unresolvedComments` AND `nitpickComments`):
 
 1. Group comments by file path and read each file once (not per-comment)
 2. If a file no longer exists, note that the comment may be outdated
-3. Assess the comment against the current code and provide your opinion:
-   - **Agree**: Explain why and offer to fix it
-   - **Disagree**: Explain why the current code is acceptable
-   - **Already fixed**: Note that the code already addresses this concern
-4. When multiple comments appear at the same file and line, they are part of the same review thread — read them together as a conversation and assess the original feedback
-5. Present your assessment in list format (renders reliably in terminals):
+3. Assess each comment against the current code. When multiple comments appear at the same file and line, they are part of the same review thread — read them together as a conversation
+4. Group your assessment as follows:
 
-   **1. `src/api.ts:118`** - Wrap JSON.parse in try-catch
-   **Verdict: Already fixed** - Try-catch added in recent commit
+   **Should address**
+   - Description of the comment with file path(s)
+     - Why it's a real issue (bug, a11y, UX, etc.)
 
-   **2. `src/config.ts:23`** - Use `const` instead of `let`
-   **Verdict: Disagree** - Value is reassigned on L31
+   **Can ignore**
+   - Description of the comment with file path(s)
+     - Why: already fixed, not actionable, not worth addressing in this PR, etc.
 
-   **3. `src/utils.ts:42`** - Add null check for user input
-   **Verdict: Agree** - Input isn't validated, could cause runtime error
-
-Then, offer to fix any issues where you agreed.
+   **Net**
+   Summary of how many are worth fixing and what kind of issues they are. Offer to fix, but **do NOT start until the user confirms**.