@clipboard-health/ai-rules 2.26.0 → 2.28.0

package/README.md

@@ -10,6 +10,7 @@ Pre-built AI agent rules for consistent coding standards. Uses a retrieval-based
   - [Include/Exclude Rules](#includeexclude-rules)
   - [Updating Rules](#updating-rules)
 - [Available Rules](#available-rules)
+- [Contributing Rules](#contributing-rules)
 - [Migration from v1](#migration-from-v1)
 - [Local development commands](#local-development-commands)
 
@@ -74,6 +75,8 @@ node sync.js common --include backend/architecture
 node sync.js backend --exclude backend/mongodb backend/postgres --include frontend/testing
 ```
 
+Unknown rule ids are skipped with a warning so a stale `--include`/`--exclude` never breaks installs.
+
 Update your `package.json` script accordingly:
 
 ```json
@@ -105,54 +108,68 @@ git commit -m "chore: update AI coding rules"
 
 ## Available Rules
 
-### common
+Each rule's "When to Read" text comes from the `description` field in the rule file's YAML frontmatter — the single source of truth used for the generated `AGENTS.md` index and the tables below.
 
-| Rule ID                       | Description                                                    |
-| ----------------------------- | -------------------------------------------------------------- |
-| `common/configuration`        | Config decisions: secrets, SSM, feature flags, DB vs hardcoded |
-| `common/coreLibraries`        | Available `@clipboard-health/*` shared libraries               |
-| `common/featureFlags`         | Feature flag naming, lifecycle, and cleanup                    |
-| `common/gitWorkflow`          | Commit messages, PR titles, and pull request guidelines        |
-| `common/loggingObservability` | Log levels, structured context, PII avoidance                  |
-| `common/testing`              | Unit test conventions and structure                            |
-| `common/typeScript`           | TypeScript naming, types, functions, error handling            |
+<!-- START: Auto-generated by ./scripts/populateReadme.ts -->
 
 ### backend
 
-| Rule ID                  | Description                                         |
-| ------------------------ | --------------------------------------------------- |
-| `backend/architecture`   | Three-tier pattern: modules, services, controllers  |
-| `backend/asyncMessaging` | Queues, async messaging, background jobs            |
-| `backend/mongodb`        | MongoDB/Mongoose: schemas, indexes, queries         |
-| `backend/notifications`  | Notification and messaging patterns                 |
-| `backend/postgres`       | Postgres queries: Prisma, subqueries, feature flags |
-| `backend/restApiDesign`  | REST API design: JSON:API, endpoints, contracts     |
-| `backend/serviceTests`   | Service-level integration tests                     |
+| Rule ID                  | When to Read                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------------- |
+| `backend/architecture`   | Structuring NestJS modules, services, repos: three-tier, microservices, ts-rest contracts |
+| `backend/asyncMessaging` | Working with queues, async messaging, or background jobs                                  |
+| `backend/infrastructure` | Provisioning infrastructure: Terraform, Docker, ECS, DNS                                  |
+| `backend/mongodb`        | Working with MongoDB/Mongoose: schemas, indexes, queries, transactions, migrations        |
+| `backend/notifications`  | Implementing notifications via Knock: push notifications, deep links, workflow design     |
+| `backend/postgres`       | Working with Postgres: column types, schema changes, query patterns, Prisma TypedSQL      |
+| `backend/restApiDesign`  | Designing REST APIs: JSON:API, auth, validation, pagination, ts-rest contracts, DTOs      |
+| `backend/serviceTests`   | Writing service tests: test data, background jobs, bug handling, migrations               |
 
-### frontend
+### common
 
-| Rule ID                            | Description                                  |
-| ---------------------------------- | -------------------------------------------- |
-| `frontend/customHooks`             | React custom hooks patterns                  |
-| `frontend/dataFetching`            | React Query, API calls, caching              |
-| `frontend/e2eTesting`              | E2E testing with Playwright                  |
-| `frontend/errorHandling`           | React error handling patterns                |
-| `frontend/fileOrganization`        | Frontend file and folder organization        |
-| `frontend/frontendTechnologyStack` | Frontend library and framework choices       |
-| `frontend/interactiveElements`     | Forms, buttons, inputs                       |
-| `frontend/modalRoutes`             | Modals and route-based dialogs               |
-| `frontend/reactComponents`         | React component patterns, props, composition |
-| `frontend/styling`                 | CSS, themes, responsive design               |
-| `frontend/testing`                 | React Testing Library, component tests       |
+| Rule ID                       | When to Read                                                                                                           |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `common/configuration`        | Adding config, secrets, or third-party dependencies: SSM, LaunchDarkly, DB, NPM packages                               |
+| `common/coreLibraries`        | Adding dependencies, implementing functionality, or debugging errors involving a @clipboard-health/\* library          |
+| `common/featureFlags`         | Creating or managing feature flags: naming, lifecycle, SDK usage, Zod schemas                                          |
+| `common/gitWorkflow`          | Writing commit messages, PR titles, or reviewing pull requests                                                         |
+| `common/libraryAuthoring`     | Authoring shared library code: @clipboard-health/\* packages or shared library modules within services (e.g., src/lib) |
+| `common/loggingObservability` | Adding logging, metrics, monitoring, or observability: levels, context, PII, Datadog                                   |
+| `common/testing`              | Writing unit tests: conventions, naming, structure                                                                     |
+| `common/typeScript`           | Writing ANY TypeScript code                                                                                            |
 
 ### datamodeling
 
-| Rule ID                                | Description                             |
-| -------------------------------------- | --------------------------------------- |
-| `datamodeling/analytics`               | Analytics data models                   |
-| `datamodeling/castingDbtStagingModels` | Data type casting in dbt staging models |
-| `datamodeling/dbtModelDevelopment`     | dbt model naming, structure, testing    |
-| `datamodeling/dbtYamlDocumentation`    | dbt YAML documentation and schema files |
+| Rule ID                                | When to Read                                                                   |
+| -------------------------------------- | ------------------------------------------------------------------------------ |
+| `datamodeling/analytics`               | Querying analytics data: dbt-mcp, Snowflake, source columns, output formatting |
+| `datamodeling/castingDbtStagingModels` | Casting data types in dbt staging models                                       |
+| `datamodeling/dbtModelDevelopment`     | Developing dbt models: naming, structure, testing                              |
+| `datamodeling/dbtYamlDocumentation`    | Writing dbt YAML documentation and schema files                                |
+
+### frontend
+
+| Rule ID                    | When to Read                                                                                                 |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `frontend/architecture`    | Frontend architecture: technology stack, file organization, where business logic lives                       |
+| `frontend/customHooks`     | Creating React custom hooks: naming, shared state with constate                                              |
+| `frontend/dataFetching`    | Implementing data fetching and error handling: React Query, API calls, caching, parsedApi                    |
+| `frontend/e2eTesting`      | Writing E2E tests with Playwright                                                                            |
+| `frontend/reactComponents` | Building UI components: structure, composition, modals, bottom sheets, interactive elements, a11y, Storybook |
+| `frontend/styling`         | Styling components with MUI sx prop: theme tokens, spacing, no CSS/SCSS                                      |
+| `frontend/testing`         | Writing frontend tests: React Testing Library, component tests                                               |
+
+<!-- END: Auto-generated by ./scripts/populateReadme.ts -->
+
+## Contributing Rules
+
+A rule earns its place only if a frontier model would do the wrong thing without it: Clipboard-specific decisions, library choices, naming, and hard-won gotchas. Do not add tutorials, generic best practices, or anything a linter already enforces.
+
+To add or change a rule:
+
+1. Edit or create the rule file under `rules/<category>/` with a frontmatter `description` (the "When to Read" text).
+2. Run `npx tsx scripts/populateReadme.ts` to regenerate the tables above (a test fails if they drift).
+3. New categories are directories under `rules/`; no registration needed.
 
 ## Migration from v1
 

package/package.json

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

package/rules/backend/architecture.md

@@ -1,3 +1,7 @@
+---
+description: "Structuring NestJS modules, services, repos: three-tier, microservices, ts-rest contracts"
+---
+
 # Architecture
 
 ## Three-Tier Architecture

package/rules/backend/asyncMessaging.md

@@ -1,3 +1,7 @@
+---
+description: "Working with queues, async messaging, or background jobs"
+---
+
 # Async Messaging & Background Jobs
 
 ## When to Use

package/rules/backend/infrastructure.md

@@ -1,3 +1,7 @@
+---
+description: "Provisioning infrastructure: Terraform, Docker, ECS, DNS"
+---
+
 # Infrastructure
 
 ## Terraform

package/rules/backend/mongodb.md

@@ -1,26 +1,8 @@
-# MongoDB/Mongoose
-
-**ObjectId:**
-
-```typescript
-import mongoose, { Types, Schema } from "mongoose";
-
-const id = new Types.ObjectId();
-
-// In schemas
-const schema = new Schema({
-  authorId: { type: Schema.Types.ObjectId, ref: "User" },
-});
-
-// In interfaces
-interface Post {
-  authorId: Types.ObjectId;
-}
+---
+description: "Working with MongoDB/Mongoose: schemas, indexes, queries, transactions, migrations"
+---
 
-// Validation
-if (mongoose.isObjectIdOrHexString(value)) {
-}
-```
+# MongoDB/Mongoose
 
 **File Structure:**
 
@@ -77,14 +59,3 @@ Run `explain("executionStats")` on new or changed queries; verify `$lookup` stag
 ## Batch Migrations
 
 Migrate large datasets in batches via background jobs using a cursor pattern (each job processes a batch and schedules the next); add 1-5s delay between batches; use the slow job group.
-
-## Repository Pattern
-
-```typescript
-class UserRepo {
-  // Named methods over generic CRUD
-  async findById(request: { id: UserId }): Promise<UserDo> {}
-  async findByEmail(request: { email: string }): Promise<UserDo> {}
-  async updateEmail(request: { id: UserId; email: string }): Promise<UserDo> {}
-}
-```

package/rules/backend/notifications.md

@@ -1,3 +1,7 @@
+---
+description: "Implementing notifications via Knock: push notifications, deep links, workflow design"
+---
+
 # Notifications
 
 Send via [Knock](https://docs.knock.app) using `@clipboard-health/notifications`. Braze is deprecated.

package/rules/backend/postgres.md

@@ -1,3 +1,7 @@
+---
+description: "Working with Postgres: column types, schema changes, query patterns, Prisma TypedSQL"
+---
+
 # Postgres
 
 ## Column Types

package/rules/backend/restApiDesign.md

@@ -1,38 +1,19 @@
+---
+description: "Designing REST APIs: JSON:API, auth, validation, pagination, ts-rest contracts, DTOs"
+---
+
 # REST API Design
 
 ## JSON:API Specification
 
-Follow [JSON:API spec](https://jsonapi.org/).
-
-```json
-{
-  "data": [
-    {
-      "id": "1",
-      "type": "shift",
-      "attributes": { "qualification": "nurse" },
-      "relationships": {
-        "assignedWorker": {
-          "data": { "type": "worker", "id": "9" }
-        },
-        "location": {
-          "data": { "type": "workplace", "id": "17" }
-        }
-      }
-    }
-  ]
-}
-```
+Follow the [JSON:API spec](https://jsonapi.org/) with these conventions:
 
 - Singular `type` values: `shift` not `shifts`
 - Links optional (use only for pagination)
 - Use `include` for related resources
 - Avoid `meta` unless necessary
 - Use lowerCamelCase for JSON keys
-
-## Error Responses
-
-Return errors using JSON:API `errors` array with `code`, `status`, and `title` fields.
+- Return errors using JSON:API `errors` array with `code`, `status`, and `title` fields
 
 ## URLs
 
@@ -44,27 +25,11 @@ POST /workers/:workerId/referral-codes
 
 ## HTTP Conventions
 
-- No PUT support — use PATCH for updates
-- POST returns the created resource DTO
-- Use only GET, POST, PATCH, DELETE
-- GET must be idempotent with no side effects
+- Use only GET, POST, PATCH, DELETE; no PUT support — use PATCH for updates
 - Model state changes as PATCH to resource attributes (not action-specific POST endpoints)
-
-## HTTP Status Codes
-
-| Code | Usage                                                 |
-| ---- | ----------------------------------------------------- |
-| 200  | GET, PATCH, DELETE success                            |
-| 201  | POST creation                                         |
-| 202  | Accepted (async processing)                           |
-| 400  | Syntactic errors or unsupported query params          |
-| 401  | Unauthenticated                                       |
-| 403  | Forbidden                                             |
-| 404  | Not found                                             |
-| 409  | Conflict                                              |
-| 422  | Semantic validation errors, unsupported filters/sorts |
-| 429  | Rate limited                                          |
-| 500  | Server error                                          |
+- POST returns the created resource DTO with 201
+- GET must be idempotent with no side effects
+- Return 400 for syntactic errors and unsupported query params; 422 for semantic validation errors and unsupported filters/sorts
 
 ## Authentication & Authorization
 
@@ -102,15 +67,6 @@ Use helpers from `@clipboard-health/contract-core` instead of raw Zod methods in
 - Export at the DTO boundary (request/response schemas), not every intermediate schema
 - Compose relationships from shared schemas — don't redefine `type` literals per contract
 
-### `parsedApi.ts` vs `api.ts`
-
-Frontend repos have two API layers:
-
-- **`api.ts`** (legacy) — does not parse responses through Zod schemas. Inferred types say `Date` for `dateTimeSchema()` fields but the runtime value is still a string. Zod transforms (`.transform()`, `dateTimeSchema()`, enum fallbacks) produce **incorrect types at runtime**.
-- **`parsedApi.ts`** — parses both inputs (`z.input`) and outputs (`z.output`) through schemas. Types match runtime values.
-
-Use `parsedApi.ts` for all new API calls. However, `parsedApi.ts` means invalid contract schemas will fail at runtime — ensure contracts are forwards-compatible. Do not use `parsedApi.ts` if the contract contains bare `z.enum()` values that the backend may extend, as new enum values will cause parse failures on old clients. Migrate bare `z.enum()` to `requiredEnumWithFallback`/`optionalEnumWithFallback` first.
-
 ## Data Transfer
 
 - Do not return database models through APIs or events; map to DTOs exposing only what clients need

package/rules/backend/serviceTests.md

@@ -1,3 +1,7 @@
+---
+description: "Writing service tests: test data, background jobs, bug handling, migrations"
+---
+
 # Service Tests (Primary Testing Approach)
 
 Test the public contract (REST endpoints, events) with real local dependencies (Postgres, Mongo, Redis). Fake slow/external services (LaunchDarkly, Firebase, Stripe, Zendesk) and other microservices with fakes; fake the event bus.

package/rules/common/configuration.md

@@ -1,3 +1,7 @@
+---
+description: "Adding config, secrets, or third-party dependencies: SSM, LaunchDarkly, DB, NPM packages"
+---
+
 # Configuration
 
 ```text

package/rules/common/coreLibraries.md

@@ -1,3 +1,7 @@
+---
+description: "Adding dependencies, implementing functionality, or debugging errors involving a @clipboard-health/* library"
+---
+
 # Core Libraries
 
 Clipboard's shared `@clipboard-health/*` libraries. Check here before adding new dependencies or implementing functionality from scratch. For details on each library:

package/rules/common/featureFlags.md

@@ -1,3 +1,7 @@
+---
+description: "Creating or managing feature flags: naming, lifecycle, SDK usage, Zod schemas"
+---
+
 # Feature Flags
 
 **Naming:** `YYYY-MM-[kind]-[subject]` (e.g., `2024-03-release-new-booking-flow`)

package/rules/common/gitWorkflow.md

@@ -1,3 +1,7 @@
+---
+description: "Writing commit messages, PR titles, or reviewing pull requests"
+---
+
 # Git Workflow
 
 - Follow Conventional Commits 1.0 spec for commit messages and PR titles.

package/rules/common/libraryAuthoring.md

@@ -0,0 +1,13 @@
+---
+description: "Authoring shared library code: @clipboard-health/* packages or shared library modules within services (e.g., src/lib)"
+---
+
+# Library Authoring
+
+Applies when writing shared library code: `@clipboard-health/*` packages and shared library modules within services (e.g., `src/lib`).
+
+- 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
+- Library API types must not contain `any` or bare `object`; prefer specific types over `unknown`, but allow `unknown` when type safety requires caller-side narrowing; use TypeScript generics
+- Define the public API exclusively through index exports (`src/index.ts` in packages); place non-public code in `internal/`
+- Strive for 100% test coverage in library code (`/* istanbul ignore next */` only for genuinely untestable lines)
+- When wrapping another library, design the API from first principles for our use cases; do not mirror the wrapped library's API or leak implementation details through interface names

package/rules/common/loggingObservability.md

@@ -1,3 +1,7 @@
+---
+description: "Adding logging, metrics, monitoring, or observability: levels, context, PII, Datadog"
+---
+
 # Logging & Observability
 
 ## Log Levels

package/rules/common/testing.md

@@ -1,8 +1,12 @@
+---
+description: "Writing unit tests: conventions, naming, structure"
+---
+
 # Testing
 
 ## Unit Tests
 
-Use when: error handling hard to trigger black-box, concurrency scenarios, >5 variations, pure function logic.
+Write unit tests for: pure function logic, error paths that are hard to trigger black-box, concurrency scenarios, and behavior with many variations (>5). Otherwise prefer testing through the public contract: service tests (backend) or component integration tests (frontend).
 
 ## Conventions
 

package/rules/common/typeScript.md

@@ -1,26 +1,32 @@
+---
+description: "Writing ANY TypeScript code"
+---
+
 # TypeScript
 
+## Domain Language
+
+- Use `worker`, not `agent`, `hcp`, or `healthcareProvider`
+- Use `workplace`, not `facility`, `hcf`, or `healthcareFacility`
+- Use `qualification`, not `agentRequirement`, `agentReq`, or `workerType`
+
 ## Naming Conventions
 
 - Avoid acronyms and abbreviations; for those widely known, use camelCase: `httpRequest`, `gpsPosition`, `cliArguments`, `apiResponse`
 - File-scoped constants: `MAX_RETRY_COUNT`
-- Instead of `agentRequirement`, `agentReq`, `workerType`, use `qualification`
-- Instead of `agent`, `hcp`, `healthcareProvider`, use `worker`
-- Instead of `facility`, `hcf`, `healthcareFacility`, use `workplace`
 
 ## Core Rules
 
-- Strict-mode TypeScript
 - Avoid type assertions (`as`, `!`) unless absolutely necessary
 - Use `function` keyword for declarations, not `const`
 - Prefer `undefined` over `null`
 - Files read top-to-bottom: exports first, internal helpers below
-- Boolean props: `is*`, `has*`, `should*`, `can*`
-- Use const assertions for constants: `as const`
 - Use immutable array methods (`toSorted`, `toReversed`) instead of mutating methods (`sort`, `reverse`)
 - Return Prisma decimal values as strings in API responses to avoid floating-point precision issues
 - Use explicit access modifiers (`public`, `private`, `protected`) on all class methods and properties
 - Use a `for` loop with `// eslint-disable-next-line no-await-in-loop` for intentional sequential execution (e.g., rate limiting, ordered processing, or resource constraints); prefer `Promise.all` when operations are independent
+- Functions take a single object argument typed by an interface and destructure it inside the function body
+- Make quantity values unambiguous: `{ amountInMinorUnits: 500, currencyCode: "USD" }`, `durationMinutes: 30`
 
 ## Dead Code Cleanup
 
@@ -35,37 +41,6 @@ In TypeScript code that has access to `@clipboard-health/util-ts`, prefer the na
 
 Import from `@clipboard-health/util-ts`.
 
-## Types
-
-```typescript
-// Quantity values—always unambiguous
-const money = { amountInMinorUnits: 500, currencyCode: "USD" };
-const durationMinutes = 30;
-```
-
-## Functions
-
-```typescript
-// Object arguments with interfaces
-interface CreateUserRequest {
-  email: string;
-  name?: string;
-}
-
-function createUser(request: CreateUserRequest): User {
-  const { email, name } = request; // Destructure inside
-  // ...
-}
-
-// Guard clauses for early returns; happy path last
-function processOrder(order: Order): Result {
-  if (!order.isValid) {
-    return { error: "Invalid order" };
-  }
-  // Main logic
-}
-```
-
 ## Error Handling
 
 - **Expected errors** (not found, validation failures): return `ServiceResult` (Either type) from `@clipboard-health/util-ts` instead of `try/catch`
@@ -90,30 +65,6 @@ throw new ServiceError({
 - 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
-- Library API types must not contain `any` or bare `object`; prefer specific types over `unknown`, but allow `unknown` when type safety requires caller-side narrowing; use TypeScript generics; define the public API exclusively through `src/index.ts` exports; place non-public code in `internal/`
-- Strive for 100% test coverage in library code (`/* istanbul ignore next */` only for genuinely untestable lines)
-- When wrapping another library, design the API from first principles for our use cases; do not mirror the wrapped library's API or leak implementation details through interface names
 
 ## Rules Engine
 

package/rules/datamodeling/analytics.md

@@ -1,6 +1,10 @@
-# About
+---
+description: "Querying analytics data: dbt-mcp, Snowflake, source columns, output formatting"
+---
 
-General knowledge for running data analysis and querying our snowflake data warehouse.
+# Analytics
+
+General knowledge for running data analysis and querying our Snowflake data warehouse.
 
 ## Understanding dbt Model Relationships and Metadata
 
@@ -12,30 +16,30 @@ Use the dbt-mcp server to:
 
 ## Querying Snowflake Data Warehouse (using Snowflake MCP)
 
-- When you need to answer data-related questions or obtain analytics by querying the Snowflake data warehouse, please use the `snowflake` mcp tool.
-- When using the Snowflake MCP to run queries, you must set the database context properly in your queries. Use fully qualified table names or set the database context to avoid connection errors.
-- The `describe_object` tool in the Snowflake MCP has a bug where it misinterprets the target_object structure, treating the table name as a database name and causing 404 "database does not exist" errors. Use `run_snowflake_query` with "DESCRIBE TABLE" instead to get table schema information successfully.
+- When you need to answer data-related questions or obtain analytics by querying the Snowflake data warehouse, use the `snowflake` MCP tool.
+- Set the database context properly in queries: use fully qualified table names or set the database context to avoid connection errors.
+- As of mid-2026, the `describe_object` tool in the Snowflake MCP has a bug where it misinterprets the target_object structure, treating the table name as a database name and causing 404 "database does not exist" errors. Use `run_snowflake_query` with "DESCRIBE TABLE" instead to get table schema information.
 
 ## Guidelines when using this knowledge
 
 - Read all of the docs.yml files to learn about the analytics schema.
 - When in doubt, read the code in the data-modeling repo to learn how each column is calculated and where the data is coming from
-- Strongly prefer to use mart models (defined inside the mart folder, those that don't have an int- or stg- prefix) before int- and stg- models
+- Strongly prefer mart models (defined inside the mart folder, those that don't have an int- or stg- prefix) before int- and stg- models
 - Strongly prefer to query tables under the analytics schema, before querying any other schemas like airbyte_db/hevo_database
 - If unsure, confirm with the user and suggest candidate tables
-- If required, you might do some data analysis using python instead of pure SQL. Connect to snowflake using a python script and then use libraries like pandas, numpy, seaborn for visualization
+- If required, you might do some data analysis using Python instead of pure SQL. Connect to Snowflake using a Python script and then use libraries like pandas, numpy, seaborn for visualization
 
 ## Output format
 
-- When running queries against snowflake and providing the user with a final answer, always show the final query that produced the result along with the result itself, so that the user is able to validate the query makes sense.
-- Once you've reached a final query that you need to show to the user, use get_metabase_playground_link to generate a playground link where the user can run the query themselves. Format it as a link with the 'metabase playground link' label as the link text, using slack's Markdown format. This is A MUST
+- Always show the final query that produced the result along with the result itself, so the user can validate the query makes sense.
+- Always use get_metabase_playground_link to generate a playground link where the user can run the query themselves; label the link "metabase playground link" (when responding in Slack, use Slack's link format).
 - Include charts or tables formatted as Markdown if needed
-- If the final result is a single number, make sure to show this prominently to the user so it's very easy to see
+- If the final result is a single number, show it prominently so it's very easy to see
 
 ## Identifying the right columns to use and how to filter data
 
-For categorical columns, you might want to select distinct values for a specific column to see what the possible options are and how to filter data
-Read the model definitions in the dbt folders to see how that column is computed and what possible values it might have
+For categorical columns, select distinct values for a specific column to see what the possible options are and how to filter data.
+Read the model definitions in the dbt folders to see how that column is computed and what possible values it might have.
 
 ## Finding Source Columns for dbt Models
 
@@ -43,6 +47,9 @@ When working on dbt model modifications and you cannot find specific fields in t
 
 ## Column Discovery Best Practices
 
-When discovering columns in Snowflake source tables, use the full table name approach with information_schema.columns and avoid LIKE clauses for more precise results. Use queries like:
-`SELECT column_name, data_type FROM airbyte_database.information_schema.columns WHERE table_name = 'EVENT' AND table_schema = 'SALESFORCE' ORDER BY ordinal_position`
-Instead of using LIKE clauses or partial matching which can be imprecise.
+When discovering columns in Snowflake source tables, query `information_schema.columns` with the full table name instead of LIKE clauses or partial matching, which can be imprecise:
+
+```sql
+SELECT column_name, data_type FROM airbyte_database.information_schema.columns
+WHERE table_name = 'EVENT' AND table_schema = 'SALESFORCE' ORDER BY ordinal_position
+```

package/rules/datamodeling/castingDbtStagingModels.md

@@ -1,3 +1,7 @@
+---
+description: "Casting data types in dbt staging models"
+---
+
 # Casting data-types for staging models
 
 1. Use declared schemas when available

package/rules/datamodeling/dbtModelDevelopment.md

@@ -1,4 +1,10 @@
-# Read the following docs in data-modeling repo
+---
+description: "Developing dbt models: naming, structure, testing"
+---
+
+# dbt Model Development
+
+Read the following docs in the data-modeling repo; they define our modeling rules, patterns, and safety constraints:
 
 - CONTRIBUTING.md
 - dbt_style_guide.md
@@ -7,21 +13,19 @@
 - models/DEVIN_ANALYST_FOLDER_STRUCTURE.md
 - .github/pull_request_template.md
 
-These define our modeling rules, patterns, and safety constraints.
-
-# Key best practices to follow
+## Key best practices to follow
 
-- DEVIN ONLY: When running dbt commands in the data-modeling repository, always reuse the existing SNOWFLAKE_SCHEMA environment variable value that is already set. Do NOT replace it with a hardcoded value like "dbt_devin" - the SNOWFLAKE_SCHEMA is set to a unique per-session string and overwriting it will cause issues.
+- When running dbt commands, reuse the existing `SNOWFLAKE_SCHEMA` environment variable value if it is already set — it is a unique per-session schema; never overwrite it with a hardcoded value.
 - Use `dbt build` to verify your changes.
-- ALL dbt staging models must have strictly defined datatypes. Please Read the "Casting DBT Staging Model Datatype Heuristic" Knowledge we have. These datatypes need to defined in the yaml documentation too.
-- When adding new fields to tables keep the original source field name format, but remove any custom field prefix (**c). For example assignment_type**c should be renamed to assignment_type. Please do not hallucinate the column field names as this is misleading for users.
-- If a source table doesn't exist. Please tell the user to ask the data-team to ingest it via the relevant ETL tool.
-- A model must always have a primary/unique key. If there's no obvious one, please create a surrogate key using a combination of fields and by looking at the data. Use `dbt_utils.generate_surrogate_key` to do so.
+- ALL dbt staging models must have strictly defined datatypes (see the `datamodeling/castingDbtStagingModels` rule). These datatypes need to be defined in the YAML documentation too.
+- When adding new fields to tables keep the original source field name format, but remove any custom field prefix (`__c`). For example `assignment_type__c` should be renamed to `assignment_type`. Verify column names against the source table before referencing them — do not guess.
+- If a source table doesn't exist, tell the user to ask the data-team to ingest it via the relevant ETL tool.
+- A model must always have a primary/unique key. If there's no obvious one, create a surrogate key using a combination of fields and by looking at the data. Use `dbt_utils.generate_surrogate_key` to do so.
 - Snapshots must be configured in YAML files (dbt 1.9+ style), not in SQL files. Define the `config` block and `relation` property in the snapshot's `.yml` file instead of using `{% snapshot %}` blocks in `.sql` files.
 
-# When creating PR's for the data-modeling repo
+## When creating PRs for the data-modeling repo
 
-- Read .github/pull_request_template.md. It contains the structure of how you would format the PR Description.
-- Under the **Validation of models** section in the PR Description, print the full table names of the dev models you've built, so it's easy for us to review the data.
+- Read .github/pull_request_template.md. It contains the structure of how to format the PR description.
+- Under the **Validation of models** section in the PR description, print the full table names of the dev models you've built, so it's easy to review the data.
 - Keep PR descriptions concise and focused. A reader should be able to quickly understand the intent and scope of the change.
 - Include the **dbt commands run** to validate the models.