Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .cursor/skills/accessibility-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,11 @@ Use this skill when reviewing user interfaces to ensure compliance with a11y sta
## Review Checklist

### 1. Keyboard & Focus Control

- **Interactive Elements:** Verify all button-like and link-like components use semantic HTML elements (`<button>`, `<a>`) rather than `div` tags with onClick handlers.
- **Focus Trapping:** Ensure modal dialogs, side drawers, and search overlays trap keyboard focus properly and support `Esc` key cancellation.

### 2. ARIA & Reader Markup

- **Labels:** Verify that icon-only buttons, custom inputs, and dynamic charts include appropriate `aria-label` or screen-reader descriptions.
- **Table Structure:** Ensure data tables (like document table facts) use correct semantic tags (`<thead>`, `<tbody>`, `<th>`) for readable text-to-speech rendering.
3 changes: 3 additions & 0 deletions .cursor/skills/ai-architecture-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,17 @@ Use this skill when reviewing or modifying the RAG (Retrieval-Augmented Generati
## Review Checklist

### 1. Retrieval Quality & Provenance

- **Hybrid Search:** Confirm queries use proper hybrid search patterns (pgvector + semantic/trigram matching) and respect user/organization boundaries.
- **Provenance / Citations:** Ensure generated answers are strongly tied to source documents and include clean, traceable citation references.
- **Fail-Closed Policy:** If no relevant documents are retrieved or verification fails, the system must degrade gracefully or return a clear "No evidence found" response rather than hallucinating.

### 2. Model Routing & Timeout Logic

- **Routing Rules:** Check that routing between fast and strong models follows defined rules (e.g. `RAG_PROVIDER_MODE`).
- **Timeouts:** Ensure LLM calls are bounded by client and server-side timeouts (e.g., `OPENAI_ANSWER_TIMEOUT_MS`).

### 3. Structured Output & Safety

- **Schema Conformity:** Validate that LLM responses use strict schema structures (e.g., OpenAI structured JSON output) to prevent parsing errors.
- **Safety Filters:** Check that toxicity, safety filters, and prompt injection mitigations are active on user inputs and LLM outputs.
4 changes: 4 additions & 0 deletions .cursor/skills/api-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,23 @@ Use this skill when reviewing or modifying API routes, endpoints, or network bou
## Review Checklist

### 1. Request Validation

- **Zod Schemas:** Ensure all incoming requests (`req.json()`, query parameters, route segments) are validated using strict Zod schemas.
- **Fail Early:** Requests failing schema validation must return `400 Bad Request` immediately before running downstream DB or AI logic.
- **Safety check:** Validate input boundaries (e.g., maximum string length, non-empty collections, limit boundaries on pagination).

### 2. Error Handling & Taxonomy

- **Closed Errors:** Avoid throwing raw database, library, or system errors to the client. Wrap exceptions in consistent JSON error envelopes.
- **HTTP Semantics:** Use correct HTTP status codes (e.g., `401 Unauthorized` vs `403 Forbidden`, `404 Not Found` for missing resources, `429 Too Many Requests` for rate limits).
- **Consistency:** Ensure error payloads follow a unified schema, containing a clear error code (e.g., `VALIDATION_FAILED`, `INTERNAL_ERROR`) and user-safe descriptions.

### 3. Response Contracts

- **Serialization:** Explicitly define the serialized JSON shape of the response. Avoid passing DB model instances directly to the frontend.
- **Pagination:** For resource listing APIs, verify pagination params (`limit`, `offset` / `cursor`) are implemented, validated, and bounded.

### 4. Authentication & Authorization

- **Server-Side Enforcement:** Do not rely on client assertions. Re-authenticate user credentials (JWT / session cookies) server-side.
- **Tenant Isolation:** Ensure fetched resources are filtered by the active user's identity (`user_id`).
2 changes: 2 additions & 0 deletions .cursor/skills/code-quality-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,12 @@ Use this skill when auditing source files for maintainability, readability, and
## Review Checklist

### 1. Maintainability & Naming

- **Clean Naming:** Ensure functions, variables, and database keys carry logical, self-describing names.
- **Decomposition:** Look for bloated files/functions that should be decomposed. Keep modules focused on a single responsibility.
- **Duplication (DRY):** Consolidate duplicate helper logic, styles, and configurations.

### 2. Logic & Complexity

- **Control Flow:** Simplify nested conditionals, deeply nested loops, or fragile edge-case handling.
- **Dead Code:** Remove unused functions, comments, or commented-out code blocks left behind.
2 changes: 2 additions & 0 deletions .cursor/skills/design-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,11 @@ Use this skill when auditing UI styling, colors, layout structures, and spacing
## Review Checklist

### 1. Style & Spacing Consistency

- **Design System Tokens:** Ensure custom components utilize predefined design variables (colors, borders, shadows, font sizes) rather than ad-hoc inline styles.
- **Layout Spacing:** Check for consistent paddings, margins, grid gaps, and alignment.

### 2. Clinical Theme Adherence

- **Layout Density:** Review components to confirm the visual target is dense, clean, calm, and fast to scan rather than overly flashy or visually expressive.
- **Browser QA / Screenshot Verification:** For major UI changes, run a local dev server with `npm run ensure` and capture screenshots to verify cross-device visual fidelity.
2 changes: 2 additions & 0 deletions .cursor/skills/frontend-architecture-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,11 @@ Use this skill when reviewing Next.js App Router structures, component boundarie
## Review Checklist

### 1. Next.js App Router Boundaries

- **RSC vs. Client Components:** Ensure components are Server Components by default. Keep client-side logic (`use state`, `use effect`, browser APIs) isolated to leaf components marked with `"use client"`.
- **Data Fetching:** Fetch data in Server Components or Server Actions where possible. Avoid calling internal `/api/...` endpoints directly from RSCs.

### 2. State & Rendering

- **State Duplication:** Avoid replicating URL/router state in local React state. Prefer URLSearchParams and next/navigation controls for search/filters.
- **Rendering Waste:** Check for unnecessary context re-renders, un-memoized expensive calculations, or excessive component mount/unmount cycles.
2 changes: 2 additions & 0 deletions .cursor/skills/performance-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,11 @@ Use this skill when reviewing query bottlenecks, database RPC latencies, client
## Review Checklist

### 1. Database & API Latency

- **Query Caching:** Verify that repetitive/expensive database fetches and RAG queries leverage caching layers (e.g. `rag_response_cache`).
- **Index Optimization:** Ensure queries leverage appropriate indices (e.g., trigram/lexical text indexes, vector HNSW).

### 2. LLM & Asset Loading

- **Token Overhead:** Check that prompt sizes and context window limits are optimized to keep API costs down.
- **Resource Streaming:** Ensure heavy document rendering, search lists, and PDF asset previews load incrementally or use lazy-loading controls.
2 changes: 2 additions & 0 deletions .cursor/skills/release-readiness-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,13 @@ Use this skill when preparing a branch for merging, pull request submission, or
## Review Checklist

### 1. Build & Automation Checks

- **Static Analysis:** Confirm `npm run lint` and `npm run typecheck` run clean.
- **Verification Gates:** Ensure the appropriate verification scripts run successfully (`npm run verify:cheap` at minimum; `npm run verify:release` for full handoffs).
- **Target database checks:** Run `npm run check:supabase-project` to confirm env targets match `Clinical KB Database` ref `sjrfecxgysukkwxsowpy`.

### 2. Clinical Governance Compliance

- **Preflight Verification:** Complete all checklist items in `.github/pull_request_template.md`.
- **Secret Scan:** Confirm no private configuration files (`.env.local`), local debug logs, or keys are present in the git stage.
- **Production Readiness Check:** Run `npm run check:production-readiness` for privacy, ingestion, or clinical behavior changes.
1 change: 1 addition & 0 deletions .cursor/skills/repo-auditor/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Use this skill when auditing the workspace layout, folder structures, imports, a
## Review Checklist

### 1. Structural Audits

- **Broken Imports:** Scan modified files for broken relative imports, incorrect library names, or obsolete modules.
- **Unused Files:** Identify and safely remove files that are truly dead and not part of route mappings, active scripts, migrations, or test resources.
- **Consolidation:** Check for identical or redundant configuration keys, environment variables, or scripts that can be safely merged.
2 changes: 2 additions & 0 deletions .cursor/skills/security-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,12 @@ Use this skill when reviewing code that touches authentication, database schemas
## Review Checklist

### 1. Key Confinement & Environment Safety

- **Service Role Key:** Ensure the Supabase `service_role` key is never exposed to public clients. Never prefix variables containing secret keys with `NEXT_PUBLIC_`.
- **Credential Storage:** Verify that credentials are not committed or hardcoded. Look for placeholder usage in `.env.example`.

### 2. Database & Storage Safety

- **Row-Level Security (RLS):** Ensure RLS is active on all public/exposed tables. Avoid deprecated checkers like `auth.role()` and prefer strict role predicates (`TO authenticated`).
- **Owner Scope Verification:** Verify that API endpoints filter queries by the authenticated user's ID (`user_id`) to prevent unauthorized cross-tenant data access.
- **Storage Buckets:** Verify that files uploaded to private buckets (`clinical-documents`, `clinical-images`) require validated user signatures for retrieval.
Expand Down
20 changes: 8 additions & 12 deletions .cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,24 @@

## [1.3.0](https://github.com/supabase/agent-skills/compare/v1.2.0...v1.3.0) (2026-06-05)


### Features

* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))

- add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
- using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))

### Bug Fixes

* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
- correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
- cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))

## [1.2.0](https://github.com/supabase/agent-skills/compare/v1.1.1...v1.2.0) (2026-06-02)


### Features

* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))

- add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
- using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))

### Bug Fixes

* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
- correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
- cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
22 changes: 12 additions & 10 deletions .cursor/skills/supabase-postgres-best-practices/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ Comprehensive performance optimization guide for Postgres, maintained by Supabas
## When to Apply

Reference these guidelines when:

- Writing SQL queries or designing schemas
- Implementing indexes or query optimization
- Reviewing database performance issues
Expand All @@ -26,16 +27,16 @@ Reference these guidelines when:

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Query Performance | CRITICAL | `query-` |
| 2 | Connection Management | CRITICAL | `conn-` |
| 3 | Security & RLS | CRITICAL | `security-` |
| 4 | Schema Design | HIGH | `schema-` |
| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
| 6 | Data Access Patterns | MEDIUM | `data-` |
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
| 8 | Advanced Features | LOW | `advanced-` |
| Priority | Category | Impact | Prefix |
| -------- | ------------------------ | ----------- | ----------- |
| 1 | Query Performance | CRITICAL | `query-` |
| 2 | Connection Management | CRITICAL | `conn-` |
| 3 | Security & RLS | CRITICAL | `security-` |
| 4 | Schema Design | HIGH | `schema-` |
| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
| 6 | Data Access Patterns | MEDIUM | `data-` |
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
| 8 | Advanced Features | LOW | `advanced-` |

## How to Use

Expand All @@ -48,6 +49,7 @@ references/_sections.md
```

Each rule file contains:

- Brief explanation of why it matters
- Incorrect SQL example with explanation
- Correct SQL example with explanation
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ to recognize anti-patterns.

Include specific metrics. Helps agents prioritize fixes.

**Good:** "10x faster queries", "50% smaller index", "Eliminates N+1"
**Good:** "10x faster queries", "50% smaller index", "Eliminates N+1"
**Bad:** "Faster", "Better", "More efficient"

### 4. Self-Contained Examples
Expand Down Expand Up @@ -105,33 +105,29 @@ Most references should focus on pure SQL patterns. This keeps examples portable.

```typescript
for (const user of users) {
const posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [
user.id,
]);
const posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [user.id]);
}
```
````

**Correct (batch query):**

```typescript
const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [
userIds,
]);
const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [userIds]);
```

---

## Impact Level Guidelines

| Level | Improvement | Use When |
|-------|-------------|----------|
| **CRITICAL** | 10-100x | Missing indexes, connection exhaustion, sequential scans on large tables |
| **HIGH** | 5-20x | Wrong index types, poor partitioning, missing covering indexes |
| **MEDIUM-HIGH** | 2-5x | N+1 queries, inefficient pagination, RLS optimization |
| **MEDIUM** | 1.5-3x | Redundant indexes, query plan instability |
| **LOW-MEDIUM** | 1.2-2x | VACUUM tuning, configuration tweaks |
| **LOW** | Incremental | Advanced patterns, edge cases |
| Level | Improvement | Use When |
| --------------- | ----------- | ------------------------------------------------------------------------ |
| **CRITICAL** | 10-100x | Missing indexes, connection exhaustion, sequential scans on large tables |
| **HIGH** | 5-20x | Wrong index types, poor partitioning, missing covering indexes |
| **MEDIUM-HIGH** | 2-5x | N+1 queries, inefficient pagination, RLS optimization |
| **MEDIUM** | 1.5-3x | Redundant indexes, query plan instability |
| **LOW-MEDIUM** | 1.2-2x | VACUUM tuning, configuration tweaks |
| **LOW** | Incremental | Advanced patterns, edge cases |

---

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,33 +7,41 @@ Take the examples below as pure demonstrative. Replace each section with the act
---

## 1. Query Performance (query)

**Impact:** CRITICAL
**Description:** Slow queries, missing indexes, inefficient query plans. The most common source of Postgres performance issues.

## 2. Connection Management (conn)

**Impact:** CRITICAL
**Description:** Connection pooling, limits, and serverless strategies. Critical for applications with high concurrency or serverless deployments.

## 3. Security & RLS (security)

**Impact:** CRITICAL
**Description:** Row-Level Security policies, privilege management, and authentication patterns.

## 4. Schema Design (schema)

**Impact:** HIGH
**Description:** Table design, index strategies, partitioning, and data type selection. Foundation for long-term performance.

## 5. Concurrency & Locking (lock)

**Impact:** MEDIUM-HIGH
**Description:** Transaction management, isolation levels, deadlock prevention, and lock contention patterns.

## 6. Data Access Patterns (data)

**Impact:** MEDIUM
**Description:** N+1 query elimination, batch operations, cursor-based pagination, and efficient data fetching.

## 7. Monitoring & Diagnostics (monitor)

**Impact:** LOW-MEDIUM
**Description:** Using pg_stat_statements, EXPLAIN ANALYZE, metrics collection, and performance diagnostics.

## 8. Advanced Features (advanced)

**Impact:** LOW
**Description:** Full-text search, JSONB optimization, PostGIS, extensions, and advanced Postgres features.
Loading