@clipboard-health/ai-rules 2.14.19 → 2.14.20

package/package.json

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

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)