claude-code-pilot 3.1.1 → 3.3.0

package/src/skills/plan-orchestrate/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: plan-orchestrate
+description: Read a plan document, decompose it into steps, design a per-step agent chain from the CCP catalogue, and emit ready-to-paste /orchestrate custom prompts. Generative only — never invokes /orchestrate itself. Use when the user has a multi-step plan and wants to drive it through orchestrate without composing chains by hand.
+origin: ECC
+---
+
+# Plan Orchestrate
+
+Bridge a plan document to `/orchestrate custom` by emitting one ready-to-paste invocation per step. The skill is generative only — it never executes `/orchestrate`. The user pastes each line when ready.
+
+## When to Activate
+
+- User has a multi-step plan document (PRD, RFC, implementation plan) and wants to drive it through `/orchestrate`.
+- User says "orchestrate this plan", "give me orchestrate prompts for each step", "compose chains for this plan".
+- A step-by-step plan exists but the user does not want to manually pick agents per step.
+
+Skip when:
+- The work is one ad-hoc step → call `/orchestrate custom` directly.
+- The plan is unreadable or empty. Lack of explicit numbering alone is not a skip condition — see the "No clear steps" edge case below.
+
+## Inputs
+
+```
+<plan-doc-path> [--lang=python|typescript|go|rust|cpp|java|kotlin|flutter|auto] [--scope=all|step:<n>|range:<a>-<b>] [--dry-run]
+```
+
+- `<plan-doc-path>` — required; relative or absolute path (`@docs/...` accepted).
+- `--lang` — reviewer language variant; defaults to `auto` (detected from project).
+- `--scope` — limits emitted steps; defaults to `all`.
+- `--dry-run` — print decomposition + chain rationale only; do not emit final prompts.
+
+## Authoritative `/orchestrate` shape (do not deviate)
+
+```
+/orchestrate custom "<agent1>,<agent2>,...,<agentN>" "<task description>"
+```
+
+- `custom` is a sequential chain; each agent's HANDOFF feeds the next.
+- Comma-separated agent list. No spaces preferred; one space tolerated.
+- No `--mode` / `--gate` / `--agents=...` flags exist — never invent them.
+- Agent names come from the catalogue in this skill. Embedded double quotes in the task description are escaped as `\"`.
+- Agent names are bare (`<name>`), matching how CCP installs them into `<claude-home>/agents/`.
+
+## Available agent catalogue (must pick from these)
+
+General:
+- `planner` — requirement restatement, risk decomposition, step planning
+- `architect` — architecture, system design, refactor proposals
+- `tdd-guide` — write tests → implement → 80%+ coverage
+- `code-reviewer` — generic code review
+- `security-reviewer` — security audit, OWASP, secret leakage
+- `refactor-cleaner` — dead code, duplicates, knip-class cleanup
+- `doc-updater` — documentation, codemap, README
+- `docs-lookup` — third-party library API lookups (Context7)
+- `e2e-runner` — end-to-end test orchestration
+- `database-reviewer` — PostgreSQL schema, migration, performance
+- `harness-optimizer` — local agent harness configuration
+- `loop-operator` — long-running autonomous loops
+- `chief-of-staff` — multi-channel triage (rarely a fit for plan steps)
+
+Build error resolvers:
+- `build-error-resolver` (generic) / `cpp-build-resolver` / `go-build-resolver` / `java-build-resolver` / `kotlin-build-resolver` / `rust-build-resolver` / `pytorch-build-resolver`
+
+Code reviewers:
+- `python-reviewer` / `typescript-reviewer` / `go-reviewer` / `rust-reviewer` / `cpp-reviewer` / `java-reviewer` / `kotlin-reviewer` / `flutter-reviewer`
+
+A misspelled agent name fails `/orchestrate`. Cross-check against this list before emitting.
+
+## How It Works
+
+### Phase 0 — Detect language
+
+1. Read `<plan-doc-path>`. If missing or empty, report and stop.
+2. Resolve `--lang`. When `auto`, run a polyglot-aware detection:
+   - Probe markers: `pyproject.toml` / `uv.lock` / `requirements.txt` → python; `package.json` → typescript; `go.mod` → go; `Cargo.toml` → rust; `CMakeLists.txt` or top-level `*.cpp` → cpp; `pom.xml` / `build.gradle` (Java) → java; `build.gradle.kts` or top-level Kotlin → kotlin; `pubspec.yaml` → flutter.
+   - **Polyglot tie-break**: if more than one marker matches, pick the language whose source files outnumber the others (count via `git ls-files`, excluding `vendor/`, `node_modules/`, `dist/`, `build/`, `.venv/`, generated files, and obvious test fixtures). On a tie or when no language exceeds 60% of source files, set `lang=unknown`.
+   - No marker matched → set `lang=unknown`.
+   - `lang=unknown` is a sentinel — it is **not** an agent name. Phase 2 rules 4 and 5 turn it into `code-reviewer` / `build-error-resolver` at chain composition time.
+4. Detect a **PyTorch sub-profile**: when `lang=python` and any of `pyproject.toml` / `requirements.txt` / `uv.lock` declares a dependency on `torch`, set `pytorch=true`. This only affects `build` chain selection (Phase 2 rule below); the reviewer remains `python-reviewer`.
+5. **Normalize any agent names declared in the plan**: if the plan text references agents by a plugin-prefixed form (e.g. `<namespace>:tdd-guide`), strip the prefix to get the bare catalogue name before validating or composing chains. CCP emits bare names only; never let a pre-prefixed name flow into the output.
+
+### Phase 1 — Decompose steps
+
+Identify "step units" in priority order:
+
+1. Explicit numbering: `## Step N` / `### Phase N` / `## N. ...` / top-level ordered list.
+2. A "Step" column in a table.
+3. `---`-separated blocks with verb-led headings.
+4. Otherwise treat each H2 as one step.
+
+Per step extract `id` (1-based), `title` (≤ 80 chars), `intent` (1–3 sentences), `tags`.
+
+### Phase 2 — Tag and pick chain
+
+Tag by intent (multi-tag allowed; chain built from primary + stacked secondaries):
+
+Trigger words below are matched case-insensitively. Multilingual plans are supported by matching the word stems in any language as long as the meaning aligns with the listed English trigger words.
+
+| Tag | Trigger words | Default chain |
+|---|---|---|
+| `design` | architecture, design, choose, evaluate, RFC | `planner,architect` |
+| `plan` | plan, breakdown, milestone | `planner` |
+| `impl` | implement, build, add, create, port | `tdd-guide,<lang>-reviewer` |
+| `test` | test, coverage, e2e, integration | `tdd-guide,e2e-runner` |
+| `refactor` | refactor, cleanup, dedupe, split | `architect,refactor-cleaner,<lang>-reviewer` |
+| `migration` | migrate, upgrade, rewrite, port | `architect,tdd-guide,<lang>-reviewer` |
+| `db` | schema, migration, index, SQL, Postgres, alembic, sqlmodel | `database-reviewer,<lang>-reviewer` |
+| `security` | encrypt, auth, secret, OWASP, PII | `security-reviewer,<lang>-reviewer` |
+| `build` | build, compile, lint failure, CI | `<lang>-build-resolver` (falls back to `build-error-resolver`) |
+| `docs` | docs, readme, codemap, changelog | `doc-updater` |
+| `lookup` | lookup, reference, API usage | `docs-lookup` |
+| `review` | review, audit, verify | `<lang>-reviewer,code-reviewer` |
+| `loop` | loop, autonomous, watchdog | `loop-operator` |
+
+Chain composition rules:
+1. **Primary tag selection**: when a step matches multiple tags, the **first one in table order** (top of the table = highest priority) is the primary; the rest are secondaries. Composition rules 2 and 3 below handle specific multi-tag combinations explicitly; otherwise, append secondary chains in tag table order.
+2. `impl` + `security` → `tdd-guide,<lang>-reviewer,security-reviewer`.
+3. `impl` + `db` → `tdd-guide,database-reviewer,<lang>-reviewer`.
+4. **Deduplicate** the resulting chain (preserve first occurrence). E.g. `review` + `lang=unknown` would yield `code-reviewer,code-reviewer` after rule 5; deduplication collapses it to `code-reviewer`.
+5. `<lang>-reviewer` resolves to `code-reviewer` when `lang=unknown`.
+6. `<lang>-build-resolver` resolves to `build-error-resolver` when `lang=unknown`. **Special case**: if Phase 0 set `pytorch=true`, use `pytorch-build-resolver` for `build` chains regardless of `<lang>`. There is no `python-build-resolver`; `--lang=python` without `pytorch=true` resolves to `build-error-resolver`.
+7. **Zero-tag steps**: if no trigger word matches, set chain to `code-reviewer` and write `no tag matched; default review-only chain` under "Chain rationale".
+8. Chain length ≤ 4 after deduplication. If exceeded, drop weakest tag (`lookup` and `docs` first).
+9. Do not pair `planner` and `architect` in an `impl` chain (token waste). Pair them only on `design` steps.
+10. Steps tagged `impl`, `refactor`, or `migration` end with a **reviewer-class** agent — any of `<lang>-reviewer`, `code-reviewer`, `security-reviewer`, or `database-reviewer`. The most domain-specific reviewer wins the tail position (e.g. rule 2's `impl+security` ends with `security-reviewer`; rule 3's `impl+db` ends with `<lang>-reviewer` because `database-reviewer` already gates the migration earlier in the chain). `test` and `build` steps are gated by their own validators (`e2e-runner` and the build resolver respectively) and do not require an additional reviewer.
+
+### Phase 3 — Compress task description
+
+Each emitted `<task description>` must:
+- Be self-contained (the first agent does not need the plan document open).
+- Start with `[Plan: <path>#step-<id>]`.
+- Include 1–3 verifiable Acceptance criteria.
+- Include a Scope guard (`Out of scope: ...`) **only if the plan declares one for this step**. Inherit verbatim. If the plan has no out-of-scope statement, omit the clause entirely — do not invent one.
+- Be 200–600 characters; one line; embedded `"` escaped as `\"`; no literal newlines.
+
+### Phase 4 — Output
+
+Emit Markdown using the bare-name form. The slash command is always `/orchestrate` and every agent name is rendered as a bare catalogue name (no namespace prefix).
+
+Output structure:
+
+````markdown
+# Plan-Orchestrate Result
+
+**Plan**: `<path>`
+**Lang**: `<detected-or-given>`
+**Steps**: <N>
+**Scope**: <all | step:n | range:a-b>
+
+## Steps overview
+
+| # | Title | Tags | Chain |
+|---|---|---|---|
+| 1 | ... | impl, db | `tdd-guide,database-reviewer,python-reviewer` |
+| ... | | | |
+
+---
+
+## Step 1 — <title>
+
+**Intent**: <1–3 sentences>
+**Tags**: <a, b>
+**Chain rationale**: <why this chain; which agent closes the loop>
+
+```bash
+/orchestrate custom "tdd-guide,database-reviewer,python-reviewer" "[Plan: docs/foo.md#step-1] <compressed task description>; Acceptance: <1–3 items>; Out of scope: <…>"
+```
+````
+
+Append a final "Batch execution" block aggregating every step's command in order so the user can paste them all at once. **Skip the Batch block in overview-only mode** (see "Large plan" edge case): when only the overview table is being emitted, there are no per-step commands to aggregate.
+
+### Phase 5 — Self-check (run before emitting)
+
+- [ ] Every agent in every chain comes from the catalogue (after stripping any plugin namespace prefix that appeared in the plan; see Phase 0 step 5).
+- [ ] All emitted agent names are bare (no namespace prefix) and the slash command is `/orchestrate`.
+- [ ] No invented `--mode` / `--gate` / `--agents=...` fields.
+- [ ] Each task description is single-line, double-quoted, with embedded `"` escaped.
+- [ ] Each task description begins with `[Plan: <path>#step-<id>]` and includes Acceptance (1–3 items). The `Out of scope:` clause is present only when inherited from the plan.
+- [ ] No duplicate agent in any chain after Phase 2 dedup.
+- [ ] Chain length ≤ 4.
+- [ ] Steps tagged `impl`/`refactor`/`migration` end with a reviewer-class agent (`<lang>-reviewer`, `code-reviewer`, `security-reviewer`, or `database-reviewer`). `test` and `build` are exempt — see Phase 2 rule 10.
+- [ ] Zero-tag steps emit `code-reviewer` with the rationale `no tag matched; default review-only chain`.
+- [ ] Overview table lists every step in the plan, regardless of `--scope`.
+- [ ] Per-step detail block count matches the resolved `--scope` (full plan when `--scope=all`; one block for `step:n`; range size for `range:a-b`). In overview-only mode, no per-step blocks and no Batch block are emitted.
+
+## Edge cases
+
+- **No clear steps**: prefer H2/H3 splitting; if still ambiguous, report "no structured steps detected" with the document outline and ask the user to confirm running by outline.
+- **Large plan (>1500 lines)**: enter **overview-only mode** — emit only the overview table and ask the user to narrow with `--scope` before re-running for details. In this mode, skip per-step detail blocks and skip the Batch execution block.
+- **Step too broad** (e.g. "complete all backend work"): do not force a single chain. Suggest splitting into N.a and N.b and propose a split.
+- **Plan declares agents** (rare): first **strip any plugin namespace prefix** (e.g. `<namespace>:tdd-guide`) to get the bare catalogue name (Phase 0 step 5), then validate against the catalogue. Replace invalid agents and explain under "Chain rationale".
+- **Polyglot project where `--lang=auto` cannot pick a winner**: set `lang=unknown`; reviewer resolves to `code-reviewer` and build resolver to `build-error-resolver`. Mention the fallback under "Chain rationale".
+
+## Examples
+
+### Example — Python plan
+
+Input:
+```
+plan-orchestrate @docs/plan/example-feature.md --lang=python
+```
+
+Excerpt of expected output:
+````markdown
+## Step 2 — Encrypt sensitive UserProfile fields
+
+**Intent**: Introduce an `EncryptedString` SQLAlchemy type and AES-GCM encrypt `birth_datetime` / `location` before persistence; load the key from an environment variable.
+**Tags**: impl, security, db
+**Chain rationale**: Security-sensitive write path, so `security-reviewer` closes the chain; `database-reviewer` validates the alembic migration; `python-reviewer` covers typing and PEP 8.
+
+```bash
+/orchestrate custom "tdd-guide,database-reviewer,python-reviewer,security-reviewer" "[Plan: docs/plan/example-feature.md#step-2] Implement EncryptedString SQLAlchemy type and migrate UserProfile.birth_datetime/location columns; key from ENV APP_DB_KEY; Acceptance: encrypt/decrypt roundtrip tests pass; alembic upgrade/downgrade clean on empty DB; no plaintext in DB after migrate; Out of scope: cross-tenant profile sharing logic"
+```
+````
+
+## Notes
+
+- Generative only. Never invoke `/orchestrate` from inside this skill.
+- Match the language of the plan document for task descriptions (agent names always remain English).
+- Do not insert "Co-Authored-By" lines or emoji in the output unless the user explicitly asks.

package/src/skills/prisma-patterns/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: prisma-patterns
+description: Prisma ORM patterns for TypeScript backends — schema design, query optimization, transactions, pagination, and critical traps like updateMany returning count not records, $transaction timeouts, migrate dev resetting the DB, @updatedAt skipped on bulk writes, and serverless connection exhaustion.
+origin: ECC
+---
+
+# Prisma Patterns
+
+Production patterns and non-obvious traps for Prisma ORM in TypeScript backends.
+Tested against Prisma 5.x and 6.x. Some behaviors differ from Prisma 4.
+
+Check the Prisma version before applying version-specific patterns:
+
+```bash
+npx prisma --version
+```
+
+Prisma 5 introduced `relationJoins`, which can load relations via JOIN rather than separate queries depending on query strategy and configuration. The `omit` field modifier and `prisma.$extends` Client Extensions API were also added. Note: `relationJoins` can cause row explosion on large 1:N relations or deep nested `include` — benchmark both approaches when relations may return many rows per parent.
+
+## When to Activate
+
+- Designing or modifying Prisma schema models and relations
+- Writing queries, transactions, or pagination logic
+- Using `updateMany`, `deleteMany`, or any bulk operation
+- Running or planning database migrations
+- Deploying to serverless environments (Vercel, Lambda, Cloudflare Workers)
+- Implementing soft delete or multi-tenant row filtering
+
+## Core Concepts
+
+### ID Strategy
+
+| Strategy | Use When | Avoid When |
+|---|---|---|
+| `@default(cuid())` | Default choice — URL-safe, sortable, no collisions | Sequential IDs needed for external systems |
+| `@default(uuid())` | Interoperability with non-Prisma systems required | High-write tables (random UUIDs fragment B-tree indexes) |
+| `@default(autoincrement())` | Internal join tables, audit logs | Public-facing IDs (exposes record count) |
+
+### Schema Defaults
+
+```prisma
+model User {
+  id        String    @id @default(cuid())
+  email     String    @unique  // @unique already creates an index — no @@index needed
+  name      String
+  role      Role      @default(USER)
+  posts     Post[]
+  createdAt DateTime  @default(now())
+  updatedAt DateTime  @updatedAt
+  deletedAt DateTime?
+
+  @@index([createdAt])
+  @@index([deletedAt, createdAt]) // composite for soft-delete + sort queries
+}
+```
+
+- Add `@@index` on every foreign key and column used in `WHERE` or `ORDER BY`.
+- Declare `deletedAt DateTime?` upfront when soft delete is a foreseeable requirement — adding it later requires a migration on a live table.
+- `updatedAt @updatedAt` is set automatically by Prisma on `update` and `upsert` only (see Anti-Patterns for bulk update trap).
+
+### `include` vs `select`
+
+| | `include` | `select` |
+|---|---|---|
+| Returns | All scalar fields + specified relations | Only specified fields |
+| Use when | You need most fields plus a relation | Hot paths, large tables, avoiding over-fetch |
+| Performance | May over-fetch on wide tables | Minimal payload, faster on large datasets |
+| Prisma 5 note | Uses JOIN by default (`relationJoins`) | Same |
+
+```ts
+// include — all columns + relation
+const user = await prisma.user.findUnique({
+  where: { id },
+  include: { posts: { select: { id: true, title: true } } },
+});
+
+// select — explicit allowlist
+const user = await prisma.user.findUnique({
+  where: { id },
+  select: { id: true, email: true, name: true },
+});
+```
+
+Never return raw Prisma entities from API responses — map to response DTOs to control exposed fields:
+
+```ts
+// BAD: leaks passwordHash, deletedAt, internal fields
+return await prisma.user.findUniqueOrThrow({ where: { id } });
+
+// GOOD: explicit DTO mapping
+const user = await prisma.user.findUniqueOrThrow({ where: { id } });
+return { id: user.id, name: user.name, email: user.email };
+```
+
+### Transaction Form Selection
+
+| Situation | Use |
+|---|---|
+| Independent operations, no inter-dependency | Array form |
+| Later step depends on earlier result | Interactive form |
+| External calls (email, HTTP) involved | Outside transaction entirely |
+
+```ts
+// Array form — batched in one round trip
+const [user, post] = await prisma.$transaction([
+  prisma.user.update({ where: { id }, data: { name } }),
+  prisma.post.create({ data: { title, authorId: id } }),
+]);
+
+// Interactive form — use tx client only, never the outer prisma client
+const post = await prisma.$transaction(async (tx) => {
+  const user = await tx.user.findUniqueOrThrow({ where: { id } });
+  if (user.role !== 'ADMIN') throw new Error('Forbidden');
+  return tx.post.create({ data: { title, authorId: user.id } });
+});
+```
+
+### PrismaClient Singleton
+
+Each `PrismaClient` instance opens its own connection pool. Instantiate once.
+
+```ts
+// lib/prisma.ts
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };
+
+export const prisma =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    log: process.env.NODE_ENV === 'development' ? ['query', 'error'] : ['error'],
+  });
+
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+```
+
+The `globalThis` pattern prevents duplicate instances during hot reload (Next.js, nodemon, ts-node-dev).
+
+### N+1 Problem
+
+Loading relations inside a loop issues one query per row.
+
+```ts
+// BAD: N+1 — one extra query per user
+const users = await prisma.user.findMany();
+for (const user of users) {
+  const posts = await prisma.post.findMany({ where: { authorId: user.id } });
+}
+
+// GOOD: single query
+const users = await prisma.user.findMany({ include: { posts: true } });
+```
+
+With Prisma 5+ `relationJoins`, the `include` form uses a single JOIN. On large 1:N sets this may increase result set size — benchmark both approaches if the relation can return many rows per parent.
+
+## Code Examples
+
+### Cursor Pagination (preferred for feeds and large datasets)
+
+```ts
+async function getPosts(cursor?: string, limit = 20) {
+  const items = await prisma.post.findMany({
+    where: { published: true },
+    orderBy: [
+      { createdAt: 'desc' },
+      { id: 'desc' }, // secondary sort prevents unstable pagination on duplicate timestamps
+    ],
+    take: limit + 1,
+    ...(cursor && { cursor: { id: cursor }, skip: 1 }),
+  });
+
+  const hasNextPage = items.length > limit;
+  if (hasNextPage) items.pop();
+
+  return { items, nextCursor: hasNextPage ? items[items.length - 1].id : null };
+}
+```
+
+Fetch `limit + 1` and pop — canonical way to detect `hasNextPage` without an extra count query. Always include a unique field (e.g. `id`) as a secondary `orderBy` to prevent unstable pagination when multiple rows share the same timestamp. Use offset pagination only when users need to jump to arbitrary pages (admin tables).
+
+### Soft Delete
+
+```ts
+// Always filter explicitly — do not rely on middleware (hides behavior, hard to debug)
+const activeUsers = await prisma.user.findMany({ where: { deletedAt: null } });
+
+await prisma.user.update({ where: { id }, data: { deletedAt: new Date() } });
+await prisma.user.update({ where: { id }, data: { deletedAt: null } }); // restore
+```
+
+### Error Handling
+
+```ts
+import { Prisma } from '@prisma/client';
+
+try {
+  await prisma.user.create({ data: { email } });
+} catch (e) {
+  if (e instanceof Prisma.PrismaClientKnownRequestError) {
+    if (e.code === 'P2002') throw new ConflictError('Email already exists');
+    if (e.code === 'P2025') throw new NotFoundError('Record not found');
+    if (e.code === 'P2003') throw new BadRequestError('Referenced record does not exist');
+  }
+  throw e;
+}
+```
+
+Common codes: `P2002` unique violation · `P2025` not found · `P2003` foreign key violation.
+
+Catch at the service boundary and translate to domain errors. Never expose raw Prisma messages to API consumers.
+
+### Connection Pool — Serverless
+
+Embed connection params directly in `DATABASE_URL` — string concatenation breaks if the URL already has query parameters (e.g. `?schema=public`):
+
+```bash
+# .env — preferred: embed params in the URL
+DATABASE_URL="postgresql://user:pass@host/db?connection_limit=1&pool_timeout=20"
+
+# With an external pooler (PgBouncer, Supabase pooler)
+DATABASE_URL="postgresql://user:pass@host/db?pgbouncer=true&connection_limit=1"
+```
+
+```ts
+// Vercel, AWS Lambda, and similar serverless runtimes: cap pool to 1 per instance
+// connection_limit and pool_timeout are controlled via DATABASE_URL
+const prisma = new PrismaClient();
+```
+
+## Anti-Patterns
+
+### `updateMany` returns a count, not records
+
+```ts
+// BAD: result is { count: 2 } — users[0] is undefined
+const users = await prisma.user.updateMany({ where: { role: 'GUEST' }, data: { role: 'USER' } });
+
+// GOOD: capture IDs first, then update, then fetch only the affected rows
+const targets = await prisma.user.findMany({
+  where: { role: 'GUEST' },
+  select: { id: true },
+});
+const ids = targets.map((u) => u.id);
+await prisma.user.updateMany({ where: { id: { in: ids } }, data: { role: 'USER' } });
+const updated = await prisma.user.findMany({ where: { id: { in: ids } } });
+```
+
+Same applies to `deleteMany` — returns `{ count: n }`, never the deleted rows.
+
+### `$transaction` interactive form times out after 5 seconds
+
+```ts
+// BAD: external call inside transaction exceeds 5s default → "Transaction already closed"
+await prisma.$transaction(async (tx) => {
+  const user = await tx.user.findUniqueOrThrow({ where: { id } });
+  await sendWelcomeEmail(user.email); // external call
+  await tx.user.update({ where: { id }, data: { emailSent: true } });
+});
+
+// GOOD: external calls outside the transaction
+const user = await prisma.user.findUniqueOrThrow({ where: { id } });
+await sendWelcomeEmail(user.email);
+await prisma.user.update({ where: { id }, data: { emailSent: true } });
+
+// Only raise timeout when bulk processing genuinely needs it
+await prisma.$transaction(async (tx) => { ... }, { timeout: 30_000 });
+```
+
+### `migrate dev` can reset the database
+
+`migrate dev` detects schema drift and may prompt to reset the DB, dropping all data.
+
+```bash
+# NEVER on shared dev, staging, or production
+npx prisma migrate dev --name add_column
+
+# Safe everywhere except local solo dev
+npx prisma migrate deploy
+
+# Check drift without applying
+npx prisma migrate diff \
+  --from-migrations ./prisma/migrations \
+  --to-schema-datamodel ./prisma/schema.prisma \
+  --shadow-database-url "$SHADOW_DATABASE_URL"
+```
+
+### Manually editing a migration file breaks future deploys
+
+Prisma checksums every migration file. Editing after apply causes `P3006 checksum mismatch` on every environment where the original already ran. Create a new migration instead.
+
+### Breaking schema changes require multi-step migration
+
+Adding `NOT NULL` to an existing column or renaming a column in one migration will lock the table or drop data. Use expand-and-contract:
+
+```bash
+# Step 1: create migration locally, then deploy
+npx prisma migrate dev --name add_new_column   # local only
+npx prisma migrate deploy                       # staging / production
+```
+
+```ts
+// Step 2: backfill data (run in a script or migration job, not in the shell)
+await prisma.user.updateMany({ data: { newColumn: derivedValue } });
+```
+
+```bash
+# Step 3: create the NOT NULL constraint migration locally, then deploy
+npx prisma migrate dev --name make_new_column_required  # local only
+npx prisma migrate deploy                               # staging / production
+```
+
+### `@updatedAt` does not fire on `updateMany`
+
+`@updatedAt` is set automatically only on `update` and `upsert`. Bulk writes leave it stale.
+
+```ts
+// BAD: updatedAt stays at its old value
+await prisma.post.updateMany({ where: { authorId }, data: { published: true } });
+
+// GOOD
+await prisma.post.updateMany({
+  where: { authorId },
+  data: { published: true, updatedAt: new Date() },
+});
+```
+
+### Soft delete + `findUniqueOrThrow` leaks deleted records
+
+`findUniqueOrThrow` throws `P2025` only when the row does not exist in the DB. Soft-deleted rows still exist and are returned without error.
+
+`findUniqueOrThrow` requires a unique constraint field in `where` — adding `deletedAt: null` alongside `id` breaks the type because `{ id, deletedAt }` is not a compound unique constraint. Use `findFirstOrThrow` instead.
+
+```ts
+// BAD: returns soft-deleted user
+const user = await prisma.user.findUniqueOrThrow({ where: { id } });
+
+// BAD: Prisma type error — { id, deletedAt } is not a unique constraint
+const user = await prisma.user.findUniqueOrThrow({ where: { id, deletedAt: null } });
+
+// GOOD: findFirstOrThrow supports arbitrary where conditions
+const user = await prisma.user.findFirstOrThrow({ where: { id, deletedAt: null } });
+```
+
+### `deleteMany` without `where` deletes every row
+
+```ts
+// BAD: silently wipes the table
+await prisma.post.deleteMany();
+
+// GOOD
+await prisma.post.deleteMany({ where: { authorId: userId } });
+```
+
+## Best Practices
+
+| Rule | Reason |
+|---|---|
+| `migrate deploy` in CI/CD, `migrate dev` only locally | `migrate dev` can reset the DB on drift |
+| Map entities to response DTOs | Prevents leaking internal fields |
+| Catch `PrismaClientKnownRequestError` at service boundary | Translate to domain errors |
+| Prefer `*OrThrow` methods over manual null checks | Throws P2025 automatically; use `findFirstOrThrow` when filtering non-unique fields |
+| `connection_limit=1` + external pooler in serverless | Prevents connection exhaustion |
+| Always provide `where` on `deleteMany` | Prevents accidental table wipe |
+| Set `updatedAt: new Date()` manually in `updateMany` | `@updatedAt` skips bulk writes |
+
+## Related Skills
+
+- `nestjs-patterns` — NestJS service layer that integrates Prisma
+- `postgres-patterns` — PostgreSQL-level indexing and connection tuning
+- `database-migrations` — multi-step migration planning for production
+- `backend-patterns` — general API and service layer design