The prisma-8 skill teaches agents the real migration model - #30123

An AI agent, mid-task in a user's project, runs this and moves on:

$ prisma migration plan --name add-user-role
✔ Planned migration 20260824_add-user-role
  from: (baseline)
  to:   f3a9c1…

from: (baseline) means the plan starts from an empty database — a full-create migration that will fail against any real one. A field tester's agent shipped exactly this, because it held the wrong mental model of the migration system: a linear chain with a "latest" tip, rather than what actually exists. The system was fine; the teaching was missing.

The decision: the prisma-8 skill — auto-installed into every project by prisma init — carries the real model, so the agents doing this work read it before they act. That's the distribution channel we built skills for: correcting stale training data with authoritative, versioned teaching that ships inside the packages it describes.

What the new reference (references/migration-model.md) teaches, built up in the order an agent needs it:

• The graph is a static artifact. Each migration is an edge recording from/to contract hashes. Branch tips and cycles are legal; no node is privileged; there is no "head" to chain from.
• Refs are the pointers. Small committed files; db records which contract the dev database has been brought to (a checkpoint — maintained implicitly by db init/db update on the default URL, and by nothing else; any --db suppresses that, regardless of URL); environment refs are CD promises; db is a default name, not a magic one.
• migration plan is offline and picks its origin as: --from (a grammar of forms including @contract, @db, and @empty), else the db ref, else from-empty.
• The trap, named: a from-empty origin over existing migrations is almost always a mistake, recognizable by exactly the from: (baseline) line above, with the three exits (set the ref, pass --from, or --from @empty deliberately).
• Both authoring loops, prescriptively: the dev loop (iterate with db init/db update, plan when settled) and the deploy loop (baseline before the first deploy, chain from the last shipped contract; deploys bring each database from its marker — the signature row inside the database recording which contract it is at — to the shipped contract, and never touch repo refs).
• Adoption and retrofit, in the code-verified order: contract infer → db sign for a pre-existing database; for a database whose contract the graph doesn't reach, plan the baseline first (that records the hash in the graph and stores the contract it names), then migration ref set db <hash> — ref set refuses hashes that aren't the to of an on-disk migration.

Sibling references taught fragments of the old model and are corrected: migrations.md claimed plan "diffs against the head of the on-disk graph" (no head exists), quickstart's canonical layout showed refs/head.json for the app space (app spaces get refs/db.json; head.json is extension-space seeding), migration-review had the wrong ref filename. SKILL.md gains the routing row plus a cross-cutting two-line trap warning that fires before any routing decision, and a manual journey test (02i) covers the scenario.

Every operational claim was verified against CLI source twice — once while authoring, once in review, which caught and fixed a wrong claim about --db suppression that sat on the trap's own causal path. pnpm lint:skills passes.

Alternatives considered. Fix the docs and reference pages only: no distribution — agents in user projects never read this repo's docs; the skill reaches them mechanically. Rely on the new refusal alone (sibling PR): errors teach at the moment of failure, which is late and one-shot; the skill teaches before the first attempt, and the two channels cover each other's gaps. Grow the existing migrations.md instead of a new reference: it already sits at 522 lines against a 350-line budget; a new routed reference keeps both findable.

Coordination: this branch truthfully states that the greenfield refusal and --from @empty don't exist on main yet — both live on the sibling PR. Whichever merges second updates those lines (this side: one bullet and one journey-test assertion).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Added guidance for understanding migration origins, database refs, migration graphs, and deploy-first workflows.
  • Clarified how migration plans choose their starting point and how to handle unexpected baseline plans.
  • Updated migration reference paths and canonical project layout.
  • Documented environment and database refs, including validation requirements and advancement behavior.

• Tests

  • Added a journey test covering incremental planning when an existing migration is present but the database ref is missing.