@clipboard-health/ai-rules 2.14.19 → 2.14.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/ai-rules",
-  "version": "2.14.19",
+  "version": "2.14.21",
   "description": "Pre-built AI agent rules for consistent coding standards.",
   "keywords": [
     "ai",

package/rules/common/coreLibraries.md

@@ -79,9 +79,7 @@ When a bug traces into a `@clipboard-health/*` library, read the source code in
 - **testing-outgoing-http**: Test helpers for outgoing HTTP requests.
 - **testing-prisma**: Test helpers for working with Prisma.
 - **testing-protobuf**: Test helpers for Protobuf.
-- **ui-components**: Clipboard's Material UI React components.
-- **ui-react**: Reusable React UI Components, hooks, and utilities.
-- **ui-theme**: Clipboard's Material UI theme.
+
 - **util-api**: API utilities.
 - **util-message**: Shared async messaging types and functions.
 - **util-protobuf**: Protobuf utilities.

package/rules/frontend/reactComponents.md

@@ -91,7 +91,7 @@ return <MemoizedChild onSave={handleSave} />;
 
 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
+1. **MUI**: Search MUI's component library for existing components before building custom ones
 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
 

package/rules/frontend/styling.md

@@ -25,32 +25,6 @@
 }} />
 ```
 
-## Merging Styles
-
-Use `mergeSxProps` from `@clipboard-health/ui-react` to merge default styles with consumer-provided sx props in generic components:
-
-```typescript
-import { mergeSxProps } from "@clipboard-health/ui-react";
-
-interface CardProps {
-  sx?: SxProps<Theme>;
-}
-
-function Card({ sx }: CardProps) {
-  return (
-    <Box
-      sx={mergeSxProps(
-        (theme) => ({
-          padding: theme.spacing(2),
-          borderRadius: theme.shape.borderRadius,
-        }),
-        sx,
-      )}
-    />
-  );
-}
-```
-
 ## Spacing
 
 Use theme spacing indices 1-12:

package/skills/local-package/SKILL.md

@@ -24,7 +24,7 @@ cbh local-package link --packages <package-names...>
 Example:
 
 ```bash
-cbh local-package link --packages ui-theme ui-components
+cbh local-package link --packages util-ts
 ```
 
 This will:
@@ -45,25 +45,26 @@ cbh local-package unlink --packages <package-names...>
 Example:
 
 ```bash
-cbh local-package unlink --packages ui-theme ui-components
+cbh local-package unlink --packages util-ts
 ```
 
 ## Workflow Example
 
-To test changes to `ui-theme` in `cbh-mobile-app`:
+To test changes to `util-ts` in `cbh-mobile-app`:
+
+1. Make changes to `util-ts` in `core-utils`
 
-1. Make changes to `ui-theme` in `cbh-core`
 2. From `cbh-mobile-app` root, run:
 
    ```bash
-   cbh local-package link --packages ui-theme
+   cbh local-package link --packages util-ts
    ```
 
 3. Test your changes in `cbh-mobile-app`
 4. When done, unlink:
 
    ```bash
-   cbh local-package unlink --packages ui-theme
+   cbh local-package unlink --packages util-ts
    ```
 
 ## Troubleshooting

package/skills/write-bug-ticket/SKILL.md

@@ -34,9 +34,11 @@ Structure and write Linear bug reports from evidence that already exists in the
 
 **Title:** Describes the SYMPTOM, not the cause. Under 70 characters. No bracket prefixes.
 
-**Simple bug** (<4 details): A paragraph with bold inline labels (**Expected:**, **Actual:**, etc.). No `##` headers needed.
+**Repository:** Always include the repository name in the ticket body. Run `git remote get-url origin | sed 's/\.git$//' | sed 's/.*[:/]\([^/]*\/[^/]*\)$/\1/'` to get the `org/repo` name. For simple bugs, include as a bold inline label. For complex bugs, include in `## Technical Context`.
 
-**Complex bug** (multi-service, intermittent, wide impact): Use `## Expected Behavior`, `## Actual Behavior`, `## Steps to Reproduce`, `## Evidence`, `## Technical Context` (optional — observables only, NOT diagnosis), `## Impact`.
+**Simple bug** (<4 details): A paragraph with bold inline labels (**Expected:**, **Actual:**, **Repository:**, etc.). No `##` headers needed.
+
+**Complex bug** (multi-service, intermittent, wide impact): Use `## Expected Behavior`, `## Actual Behavior`, `## Steps to Reproduce`, `## Evidence`, `## Technical Context` (include repository — observables only, NOT diagnosis), `## Impact`.
 
 **Metadata:** Priority, labels (`bug`), presented BELOW the body. Always ask for team/assignee.
 
@@ -58,3 +60,4 @@ See reference.md for full examples.
 | STR invented from assumptions  | "Not yet reproduced. Observed via monitoring."                          |
 | Guessed team assignment        | Ask the user — never guess                                              |
 | Bracket title prefixes         | Describe the symptom without brackets                                   |
+| Missing repository             | Include repo name in ticket body — derive from git remote               |

package/skills/write-bug-ticket/reference.md

@@ -27,6 +27,8 @@ Nurses on the mobile app are unable to complete shift bookings. After submitting
 
 **Actual Behavior:** Spinner runs indefinitely. App must be force-closed.
 
+**Repository:** ClipboardHealth/core-utils
+
 **Evidence:**
 
 - [RUM: session for user 12345 showing hang](https://app.datadoghq.com/rum/...)
@@ -58,6 +60,8 @@ Not yet reproduced manually. Observed via monitoring.
 
 ## Technical Context
 
+**Repository:** ClipboardHealth/core-utils
+
 Errors began at 2026-03-12 14:00 UTC. Error logs reference `MongoServerError: connection pool exhausted`. Correlates with deploy at 13:45 UTC.
 
 ## Impact

package/skills/write-feature-ticket/SKILL.md

@@ -53,15 +53,17 @@ Before drafting, verify ALL of these. If any fail, bounce back to `interview-fea
 
 **Title:** Short, imperative, describes the CAPABILITY — not the implementation. Under 70 characters.
 
+**Repository:** Always include the repository name in the ticket body. Run `git remote get-url origin | sed 's/\.git$//' | sed 's/.*[:/]\([^/]*\/[^/]*\)$/\1/'` to get the `org/repo` name. For simple features, include as a bold inline label at the end. For complex features, include in `## Context`.
+
 **Simple feature** (single user story, <4 acceptance criteria):
-A paragraph stating the problem and who it affects, then acceptance criteria as a checklist. No section headers.
+A paragraph stating the problem and who it affects, then acceptance criteria as a checklist, then repository. No section headers.
 
 **Complex feature** (multiple user stories, 4+ AC, or cross-cutting):
 Sections as needed:
 
 - `## Problem` — who is affected, what they can't do today, why it matters
 - `## Acceptance Criteria` — observable outcomes checklist
-- `## Context` — links to HLD, related tickets (linking to technical docs is fine; inlining implementation details is not)
+- `## Context` — repository, links to HLD, related tickets (linking to technical docs is fine; inlining implementation details is not)
 - `## Scope` — in/out, if ambiguity exists
 
 **Sub-issues** (when decomposed):

package/skills/write-feature-ticket/examples.md

@@ -22,6 +22,8 @@ Workplaces using phone interviews receive a daily interview digest email that is
 - [ ] Workplaces using phone interviews do not receive the digest by default
 - [ ] When a workplace switches to phone interviews, the digest is automatically disabled
 
+**Repository:** ClipboardHealth/core-utils
+
 ## Complex Ticket (with sub-issues)
 
 **Parent — Title:** Allow workplaces to disable the daily interview digest
@@ -38,6 +40,10 @@ Workplaces using phone interviews receive a daily interview digest email that is
 - [ ] When a workplace switches to phone interviews, the digest is automatically disabled
 - [ ] Only employee admins can change this setting (not workplace admins)
 
+### Context
+
+**Repository:** ClipboardHealth/core-utils
+
 ### Scope
 
 - **In:** Per-workplace toggle, auto-disable for phone interview workplaces

package/skills/write-feature-ticket/red-flags.md

@@ -15,3 +15,4 @@ Check every row before showing the draft to the user. If any apply, fix before p
 | Parroting technical input               | User says "field X", ticket says "field X"                                    | Translate to user-facing language. The ticket reader shouldn't need to know the codebase.                                                      |
 | Invented details                        | Plausible-sounding claims not from conversation or research                   | Remove. If the detail is needed, bounce back to the interview skill.                                                                           |
 | No decomposition for multi-outcome work | Two independent user-facing outcomes in one ticket                            | Split into parent + sub-issues, each describing one deliverable outcome                                                                        |
+| Missing repository                      | No repo specified in ticket body                                              | Include repo name — derive from git remote                                                                                                     |

package/skills/write-tech-debt-ticket/SKILL.md

@@ -13,7 +13,7 @@ Draft Linear tech debt tickets that justify _why_ the debt matters — cost to c
 
 ## Process
 
-1. **Gather context** — from code, PR comment, conversation, or audit
+1. **Gather context** — from code, PR comment, conversation, or audit. Note how the debt was discovered (see Discovery Context below).
 2. **Analyze the code** — read the actual code. Understand what it does and why it qualifies as debt.
 3. **Classify** — pick a primary debt type (and optional secondary) from classification table in reference.md
 4. **Gather evidence** (driven by classification):
@@ -29,7 +29,7 @@ Draft Linear tech debt tickets that justify _why_ the debt matters — cost to c
 
 ## Hard Rules
 
-- **Debt ticket, not refactoring task.** Document the cost. NEVER include "Proposed Solution", "Suggested Fix", "Acceptance Criteria", or implementation steps. You may describe _ideal state_ (destination) but NOT steps to get there.
+- **Debt ticket, not refactoring task.** Document the cost. NEVER include "Proposed Solution", "Suggested Approach", "Suggested Fix", "Acceptance Criteria", or implementation steps. You may describe _ideal state_ (destination) but NOT steps to get there.
 - **"Impact If Left Unaddressed" is MANDATORY.** What happens in 3-6 months if nobody fixes this? Without this, the ticket is just a complaint.
 - **Always read the code.** Every claim backed by a code reference or data. No vibes.
 - **Justify every rating.** Cite git history, Datadog data, or workaround examples.
@@ -45,9 +45,13 @@ Draft Linear tech debt tickets that justify _why_ the debt matters — cost to c
 
 **Title:** Describes the debt, not the fix. Under 70 characters. No bracket prefixes.
 
-**Simple debt** (single location, clear impact): A paragraph with classification, code references, and "Impact If Left Unaddressed" inline.
+**Repository:** Always include the repository name in the ticket body. Run `git remote get-url origin | sed 's/\.git$//' | sed 's/.*[:/]\([^/]*\/[^/]*\)$/\1/'` to get the `org/repo` name. For simple debt, include as a bold inline label. For complex debt, include in `## What Is The Debt`.
 
-**Complex debt** (multi-file, systemic, high-stakes): Use `## What Is The Debt`, `## Debt Classification` (type + rated interest/risk with justifications), `## Code References`, `## Evidence`, `## Ideal State` (destination, not route), `## Suggested Approach` (optional — only when fix is well-understood AND user has context implementer wouldn't, 2-3 sentences max), `## Impact If Left Unaddressed`.
+**Discovery Context:** If the debt was discovered while working on a specific ticket, PR, or incident, include that context so reviewers understand how it surfaced. For simple debt, add a sentence (e.g., "Discovered while working on [TICKET-123](link)."). For complex debt, include a `## Discovery Context` section with the originating ticket/PR link and a brief note on how the work revealed the debt. Omit this section only if the debt was found through a standalone audit with no originating ticket.
+
+**Simple debt** (single location, clear impact): A paragraph with classification, repository, code references, discovery context (if applicable), and "Impact If Left Unaddressed" inline.
+
+**Complex debt** (multi-file, systemic, high-stakes): Use `## What Is The Debt` (include repository), `## Discovery Context` (if applicable — originating ticket/PR and how the work revealed the debt), `## Debt Classification` (type + rated interest/risk with justifications), `## Code References`, `## Evidence`, `## Ideal State` (destination, not route), `## Impact If Left Unaddressed`.
 
 **Metadata:** Priority, labels (`technical-debt`), presented BELOW the body. Always ask for team/assignee.
 
@@ -55,15 +59,18 @@ See reference.md for classification tables, rating framework, and full examples.
 
 ## Red Flags — Self-Review Before Presenting
 
-| Anti-Pattern                      | Fix                                                      |
-| --------------------------------- | -------------------------------------------------------- |
-| Reads like a refactoring task     | Rewrite to document the cost of the debt, not the fix    |
-| Has "Proposed Solution" section   | Delete. Describe ideal state instead.                    |
-| Has "Acceptance Criteria"         | Delete. This is a debt ticket, not a task.               |
-| No code references                | Add specific file paths and line numbers                 |
-| Unjustified ratings               | Cite git frequency, Datadog data, or workaround examples |
-| Aesthetic complaints as debt      | Explain the concrete cost or don't file the ticket       |
-| No "Impact If Left Unaddressed"   | Always include — this gets the ticket prioritized        |
-| No Datadog for perf/reliability   | You MUST search Datadog for these types                  |
-| Forced Datadog on maintainability | Only for performance/reliability/scalability             |
-| Guessed team assignment           | Ask the user                                             |
+| Anti-Pattern                      | Fix                                                       |
+| --------------------------------- | --------------------------------------------------------- |
+| Reads like a refactoring task     | Rewrite to document the cost of the debt, not the fix     |
+| Has "Proposed Solution" section   | Delete. Describe ideal state instead.                     |
+| Has "Suggested Approach" section  | Delete. Describe ideal state instead.                     |
+| Has "Acceptance Criteria"         | Delete. This is a debt ticket, not a task.                |
+| No code references                | Add specific file paths and line numbers                  |
+| Unjustified ratings               | Cite git frequency, Datadog data, or workaround examples  |
+| Aesthetic complaints as debt      | Explain the concrete cost or don't file the ticket        |
+| No "Impact If Left Unaddressed"   | Always include — this gets the ticket prioritized         |
+| No Datadog for perf/reliability   | You MUST search Datadog for these types                   |
+| Forced Datadog on maintainability | Only for performance/reliability/scalability              |
+| Guessed team assignment           | Ask the user                                              |
+| Missing repository                | Include repo name in ticket body — derive from git remote |
+| Missing discovery context         | If debt was found during ticket/PR work, link it          |

package/skills/write-tech-debt-ticket/reference.md

@@ -37,6 +37,8 @@ Each: High/Medium/Low with a one-line justification backed by evidence.
 
 **Title:** Shift matching query scans full collection on every request
 
+**Repository:** ClipboardHealth/core-utils. Discovered while working on [ENG-4521](https://linear.app/clipboard-health/issue/ENG-4521) (shift booking latency improvements) — investigation revealed the missing index as a separate concern from the ticket's scope.
+
 The shift matching query in `src/services/booking/shiftMatcher.ts:142` executes `find({ facility, status: 'open' })` without an index on the `facility` field. Every matching request scans ~200k documents instead of the ~50 that match.
 
 **Type:** Performance | **Interest:** High — 847 requests/day hit this path. p99 latency is 4.2s vs ~120ms baseline for indexed queries ([APM: shift matching latency](https://app.datadoghq.com/apm/...)). **Incident Risk:** Medium — a traffic spike during peak booking could exhaust the connection pool. **Velocity Risk:** Low — code is stable, rarely modified.
@@ -55,8 +57,14 @@ Suggested metadata: Priority: High
 
 #### What Is The Debt
 
+**Repository:** ClipboardHealth/core-utils
+
 Four cron jobs (`DailyDigestCron`, `ShiftReminderCron`, `CredentialExpiryCron`, `TimesheetReminderCron`) each implement their own notification dispatch: recipient resolution, template selection, channel routing, and retry handling. The implementations are nearly identical but have diverged — each has different retry behavior and error handling, making it impossible to reason about notification reliability as a whole.
 
+#### Discovery Context
+
+Discovered while implementing push notification support for [ENG-3891](https://linear.app/clipboard-health/issue/ENG-3891). Adding the new channel required duplicating dispatch logic into a fifth cron job, revealing the extent of the divergence.
+
 #### Classification
 
 - **Type:** Maintainability (primary), Reliability (secondary)