# Record Gotchas

Capture surprises, workarounds, and rough edges hit while *consuming* the public...

- Repository: https://github.com/prisma/orm (47661 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add prisma/orm --skill record-gotchas -g -a claude-code -y`
Codex: `npx skills add prisma/orm --skill record-gotchas -g -a codex -y`
Cursor: `npx skills add prisma/orm --skill record-gotchas -g -a cursor -y`
Gemini CLI: `npx skills add prisma/orm --skill record-gotchas -g -a gemini-cli -y`

## Description

Capture surprises, workarounds, and rough edges hit while *consuming* the public surface of Prisma 8, Prisma Compute, or Prisma Postgres, anything a real user of these products would experience. Fires whenever an operator (or agent) writes a workaround, hits a surprising failure mode, or finds undocumented behaviour while using one of these three products from the outside (extension authoring, example apps, integration tests, customer reproductions, internal demos, manual repros). Does NOT fire on bugs in code the operator's own team maintains, those are normal product-backlog bugs. In product-team repos (e.g. `prisma-8-ws`), surfaces the gotcha and offers the operator three paths (capture-as-gotcha, file a normal bug, or note-and-move-on). Outside product-team repos (pet projects, hackathon entries, customer codebases), silent-captures into the project's gotchas log AND a Triage-state Linear ticket in the matching gotchas project, no operator escalation. Do not skip the recording step.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Record a gotcha

A **gotcha** is friction that a *consumer* of Prisma 8, Prisma Compute, or Prisma Postgres would feel, something an external user of those products would also experience: a surprising failure mode, an undocumented behaviour, a workaround you wrote, a mental model mismatch with the CLI / runtime / docs. The signal is the consumer's perspective, not the project context, you can hit a gotcha while writing an extension, working in an example app, reproducing a customer report, running an integration test against the public surface, or building anything that consumes the product from the outside.

A gotcha is **not** a bug in code your team maintains. If you own the surface and you can fix it, that's a normal product bug, filed in the regular product backlog, not a gotcha.

This skill is the canonical workflow for capturing gotchas. When the trigger fires:

1. Determine whether you're in a product-team repo or somewhere else, the escalation mode depends on it (see § Escalation mode).
2. Write a short entry to the matching gotchas log (`gotchas.md` or a per-product file).
3. File a Triage-state ticket in the matching `*-gotchas` Linear project.
4. Cross-link the two so future readers can navigate either way.

When in doubt about whether something is gotcha-worthy, capture it. The cost of a near-duplicate entry is trivial; the cost of losing the learning is permanent.

> **This skill is not optional for qualifying gotchas.** If you wrote a workaround, consulted source code, or hit a behaviour that didn't match the docs while consuming the product, run this skill before the conversation ends.

---

## Consuming vs. maintaining, the boundary

The trigger depends on the *role* the operator is wearing in the moment, not on the repo they're sitting in.

The rest: https://github.com/prisma/orm/blob/HEAD/skills-contrib/record-gotcha/SKILL.md