docs(record-upgrade-instructions): note coverage gate only checks dir existence, not per-PR entry

Signed-off-by: Will Madden <madden@prisma.io>

Author: wmadden

skills-contrib/record-upgrade-instructions/SKILL.md

@@ -104,7 +104,7 @@ The PR that introduces the breaking change must contain, in addition to the fram
 - **The post-instructions state of every affected substrate** — these substrates would have been left broken without the entry; the entry's effect on the substrate *is* the diff that brings them back to green. The PR-branch substrate state and the validation-by-execution output state must be identical.
 - **A reference in the PR description naming each entry directory** (e.g. *"Adds entries to `skills/upgrade/prisma-next-upgrade/upgrades/0.7-to-0.8/` and `skills/extension-author/prisma-next-extension-upgrade/upgrades/0.7-to-0.8/`."*).
 
-The human reviewer + the CI gate (`pnpm check:upgrade-coverage`) both check this shape. The gate catches the structural case (substrate diff without matching entry); the reviewer catches the semantic case (entry exists but its prose / scripts don't match the framework change).
+The human reviewer + the CI gate (`pnpm check:upgrade-coverage`) both check this shape, but the gate is **necessary-but-not-sufficient** — it only asserts that the in-flight transition *directory* exists, not that *this PR's* substrate diff has a matching `changes[]` entry. So a PR can have a real substrate diff, contribute no entry, and still pass the gate green whenever an earlier PR already created the transition directory. (This is exactly how a breaking change can ship undocumented: the directory was already there, so the gate stayed green.) The gap is load-bearing for the reviewer: **the human reviewer must verify that every substrate diff in the PR has a corresponding entry** — the gate will not catch a missing entry once the directory exists. The reviewer also catches the semantic case (entry exists but its prose / scripts don't match the framework change).
 
 ## Cross-audience entries (duplication)