Record a gotcha

A gotcha is friction that a consumer of Prisma Next, 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.