From 9f7860d6739e1ae17b5ccffce513032432f3a787 Mon Sep 17 00:00:00 2001 From: Oleksii Orlenko Date: Thu, 20 Aug 2026 15:21:12 +0200 Subject: [PATCH 1/4] docs(skills): fix claims-vs-reality drift from the skills audit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An audit of the 18 skills beside record-upgrade-instructions found paths that resolve nowhere, commands whose output no longer matches, and examples that outlived the code they cite. The corrections are mechanical: each one replaces a claim with what the tree, the scripts or the templates actually do. Dead references: the visitor example pointed at a file that dispatches through polymorphic hooks now, and create-pr sent readers to a skill installed from another repo. Phantom path segments in the release-notes recipe URLs made every migration link 404, in the skill and in docs/releases/README.md alike. Templates that had grown a section: contrib-pr and create-pr both list the PR template's headers, and neither mentioned the Skill update section its checklist asks you to confirm. Two agent files named models the harness cannot resolve, one table promised a column its renderer does not emit, and two instructions had no runnable form until now — reacting to a thread and detecting pending reviews each got the exact gh api call. Claude-Session: https://claude.ai/code/session_01NnNjsNcPMtbJZhnZz5Zzbe Signed-off-by: Oleksii Orlenko --- docs/releases/README.md | 14 ++++---- skills-contrib/ast-visitor-pattern/SKILL.md | 7 ++-- skills-contrib/bumping-biome/SKILL.md | 2 +- skills-contrib/contrib-pr/SKILL.md | 15 ++++---- skills-contrib/create-pr/SKILL.md | 8 +++-- skills-contrib/draft-release-notes/SKILL.md | 36 +++++++++---------- .../github-review-iteration/SKILL.md | 4 ++- skills-contrib/psl-ast-layers/SKILL.md | 2 +- skills-contrib/publish-npm-version/SKILL.md | 6 ++-- skills-contrib/record-gotcha/SKILL.md | 6 ++-- .../review-implement-phase/SKILL.md | 5 +-- .../agents/review-implementer.md | 3 +- skills-contrib/review-triage-phase/SKILL.md | 2 +- .../agents/review-triager.md | 13 +++---- .../write-architecture-docs/SKILL.md | 2 +- 15 files changed, 66 insertions(+), 59 deletions(-) diff --git a/docs/releases/README.md b/docs/releases/README.md index ec8bb43615bd..02220586b376 100644 --- a/docs/releases/README.md +++ b/docs/releases/README.md @@ -16,9 +16,9 @@ These files are drafted automatically by the [`draft-release-notes`](../../skill - **Write for users, not maintainers.** The audience is someone upgrading their app, not the team that shipped the change. Do not carry internal `TML-NNNN:` issue prefixes — link the PR instead. - **Categorize** entries under the fixed section order below, and **omit any section that has no entries**. - **Lead with breaking changes** — they are what a reader scanning the notes most needs to see. -- **Show the impact of breaking changes with a short before/after example.** For the code-visible breaking changes (contract-shape changes, authoring-surface changes, runtime-option changes), nest a compact `before` / `after` snippet under the prose bullet so a reader can see the change at a glance. Source the snippet from the matching `-to-` upgrade recipe so it stays accurate. Lead with PSL (```` ```prisma ````) when the change is on the authoring surface; use TS/JSON only when the change is genuinely a TS/emitted-shape change. Operational-only breaks (version floors, peer-dep changes, package removals) need no example. -- **Link PRs and contributors as absolute markdown links** — `[#1234](https://github.com/prisma/prisma-next/pull/1234)` and `[@handle](https://github.com/handle)`, never bare `#1234` / `@handle`. Bare references only autolink inside the GitHub Release body, **not** when this file is read as a repo file or in PR review; explicit links work in every context. Attribute contributors, especially first-time ones. -- **Link migration recipes as absolute, tag-pinned URLs** — `https://github.com/prisma/prisma/blob/v/skills/upgrade/prisma-next-upgrade/upgrades/-to-/` — not repo-relative paths. This file is published verbatim as the GitHub Release body, where repo-relative links do not resolve; pinning to the release tag keeps the link working and rot-proof. +- **Show the impact of breaking changes with a short before/after example.** For the code-visible breaking changes (contract-shape changes, authoring-surface changes, runtime-option changes), nest a compact `before` / `after` snippet under the prose bullet so a reader can see the change at a glance. Source the snippet from the matching `` upgrade recipe so it stays accurate. Lead with PSL (```` ```prisma ````) when the change is on the authoring surface; use TS/JSON only when the change is genuinely a TS/emitted-shape change. Operational-only breaks (version floors, peer-dep changes, package removals) need no example. +- **Link PRs and contributors as absolute markdown links** — `[#1234](https://github.com/prisma/prisma/pull/1234)` and `[@handle](https://github.com/handle)`, never bare `#1234` / `@handle`. Bare references only autolink inside the GitHub Release body, **not** when this file is read as a repo file or in PR review; explicit links work in every context. Attribute contributors, especially first-time ones. +- **Link migration recipes as absolute, tag-pinned URLs** — `https://github.com/prisma/prisma/blob/v/skills/prisma-next-upgrade/upgrades//` — not repo-relative paths. This file is published verbatim as the GitHub Release body, where repo-relative links do not resolve; pinning to the release tag keeps the link working and rot-proof. The section order is: **Breaking changes → Features → Fixes → New contributors**. @@ -38,7 +38,7 @@ Copy this into `docs/releases/v.md` and fill it in, dropping any sectio ## Breaking changes -- **** — . See the [migration recipe](https://github.com/prisma/prisma/blob/v/skills/upgrade/prisma-next-upgrade/upgrades/-to-/). ([#](https://github.com/prisma/prisma-next/pull/)) +- **** — . See the [migration recipe](https://github.com/prisma/prisma/blob/v/skills/prisma-next-upgrade/upgrades//). ([#](https://github.com/prisma/prisma/pull/)) Before: @@ -54,15 +54,15 @@ Copy this into `docs/releases/v.md` and fill it in, dropping any sectio ## Features -- . ([#](https://github.com/prisma/prisma-next/pull/)) +- . ([#](https://github.com/prisma/prisma/pull/)) ## Fixes -- . ([#](https://github.com/prisma/prisma-next/pull/)) +- . ([#](https://github.com/prisma/prisma/pull/)) ## New contributors -- [@](https://github.com/) made their first contribution in [#](https://github.com/prisma/prisma-next/pull/) +- [@](https://github.com/) made their first contribution in [#](https://github.com/prisma/prisma/pull/) ```` ## See also diff --git a/skills-contrib/ast-visitor-pattern/SKILL.md b/skills-contrib/ast-visitor-pattern/SKILL.md index f328b9d02680..61e69149a187 100644 --- a/skills-contrib/ast-visitor-pattern/SKILL.md +++ b/skills-contrib/ast-visitor-pattern/SKILL.md @@ -14,7 +14,7 @@ When a discriminated union has **3+ variants** and **2+ dispatch sites** (render ## Structure -Four pieces, always in the same file: +Four pieces, usually in one file — the Mongo DDL set below spreads them over three: ```typescript // 1. Abstract base (not exported — consumers use the union type) @@ -93,5 +93,6 @@ export function bar(value: string): Foo { return Object.freeze({ kind: 'bar', va ## Codebase examples -- `MongoAstNode` / `MongoDdlCommandVisitor` — `packages/2-mongo-family/4-query/query-ast/src/ddl-commands.ts` -- `OpFactoryCall` / `OpFactoryCallVisitor` — `packages/3-mongo-target/1-mongo-target/src/core/op-factory-call.ts` +- `MongoAstNode` base — `packages/2-mongo-family/4-query/query-ast/src/ast-node.ts` +- `MongoDdlCommandVisitor` interface — `packages/2-mongo-family/4-query/query-ast/src/ddl-visitors.ts` +- Concrete DDL commands and their union — `packages/2-mongo-family/4-query/query-ast/src/ddl-commands.ts` diff --git a/skills-contrib/bumping-biome/SKILL.md b/skills-contrib/bumping-biome/SKILL.md index 23de07a44e7a..461c859d3999 100644 --- a/skills-contrib/bumping-biome/SKILL.md +++ b/skills-contrib/bumping-biome/SKILL.md @@ -9,7 +9,7 @@ description: Bumps `biome` package versions (e.g. `@biomejs/biome`) using `pnpm` 1. Run `pnpm up -D -w -r @biomejs/biome@` - replace `` with a specific package version provided in the session, otherwise fallback to `latest`. -2. Rename all `biome.json` files to `biome.jsonc` and replace the old package version number in `$schema` with the newly installed package version number from the previous step. +2. If any `biome.json` files remain, rename them to `biome.jsonc`. Then replace the old package version number in `$schema` with the newly installed package version number from the previous step, in every `biome.jsonc`. 3. Run `pnpm -w lint:fix`. Report any issues/regressions briefly. diff --git a/skills-contrib/contrib-pr/SKILL.md b/skills-contrib/contrib-pr/SKILL.md index 96cd5809263d..3db27d56b44b 100644 --- a/skills-contrib/contrib-pr/SKILL.md +++ b/skills-contrib/contrib-pr/SKILL.md @@ -1,11 +1,11 @@ --- name: contrib-pr -description: Open a high-quality external contributor PR against prisma-next. Use when the user is an outside contributor (not a Prisma maintainer) and wants to submit a change as a pull request from a fork. Encodes the contribution flow from CONTRIBUTING.md so the resulting PR passes review on the first round. +description: Open a high-quality external contributor PR against prisma/prisma. Use when the user is an outside contributor (not a Prisma maintainer) and wants to submit a change as a pull request from a fork. Encodes the contribution flow from CONTRIBUTING.md so the resulting PR passes review on the first round. --- # Contributor PR skill (external) -This skill is for **external contributors** to `prisma/prisma` who are using an LLM-based agent to author or finalize a PR. It is intentionally separate from the maintainer-facing `create-pr` skill: it does not depend on Linear access, internal plan/spec documents, or any private context. It encodes the expectations laid out in [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) as a runnable workflow, so the PR you produce matches the shape maintainers expect on the first review round. +This skill is for **external contributors** to `prisma/prisma` who are using an LLM-based agent to author or finalize a PR. It is intentionally separate from the maintainer-facing `create-pr` skill: it does not depend on Linear access, internal plan/spec documents, or any private context. It encodes the expectations laid out in [`CONTRIBUTING.md`](../../CONTRIBUTING.md) as a runnable workflow, so the PR you produce matches the shape maintainers expect on the first review round. If the user is a maintainer with access to internal Linear tickets, use `create-pr` instead. @@ -38,9 +38,9 @@ This skill is a pit of success — there is no CI gate that checks you used it. Before doing anything else, read the project's contribution docs: -1. Read [`CONTRIBUTING.md`](../../../CONTRIBUTING.md). This is the source of truth for setup, the test command set, DCO signoff, and PR expectations. -2. Read [`CODE_OF_CONDUCT.md`](../../../CODE_OF_CONDUCT.md) so you understand what's expected in your interactions on the PR thread. -3. Skim [`SECURITY.md`](../../../SECURITY.md). If your change is fixing a security issue, **stop and use the Private Vulnerability Reporting flow instead** — do not open a public PR. +1. Read [`CONTRIBUTING.md`](../../CONTRIBUTING.md). This is the source of truth for setup, the test command set, DCO signoff, and PR expectations. +2. Read [`CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md) so you understand what's expected in your interactions on the PR thread. +3. Skim [`SECURITY.md`](../../SECURITY.md). If your change is fixing a security issue, **stop and use the Private Vulnerability Reporting flow instead** — do not open a public PR. If anything in `CONTRIBUTING.md` contradicts what this skill says, `CONTRIBUTING.md` wins. @@ -114,15 +114,16 @@ Examples: - `fix(postgres-adapter): handle null in jsonb columns` - `docs(contributing): clarify pnpm install steps` -The PR title flows directly into the auto-generated GitHub Release notes when the version that contains it is published — pick a title a downstream user would understand. +PR titles are the raw material the release-notes author triages when a version ships, so pick a title a downstream user would understand. #### Body -Fill in the [pull request template](../../../.github/PULL_REQUEST_TEMPLATE.md) sections in order: +Fill in the [pull request template](../../.github/PULL_REQUEST_TEMPLATE.md) sections in order: - **Linked issue**: `Fixes #N` / `Refs #N`. If no issue exists because the change is small, write `n/a — small change`. - **Summary**: one or two sentences focused on *why*, not file-by-file *what*. "Adds X because Y was broken" rather than "Adds X function in foo.ts and modifies bar.ts". - **Testing performed**: list the actual `pnpm test:*` commands you ran. If you ran a manual repro (e.g. against the demo), say so. +- **Skill update**: say which agent skill the change teaches, or write `n/a — internal only` when the change touches nothing an agent skill describes. The checklist below asks you to confirm this section. - **Checklist**: confirm DCO signoff, scope, tests, conventional title. - **Notes for the reviewer** (optional): alternative approaches you considered, follow-ups intentionally deferred, anything you want the reviewer to focus on. diff --git a/skills-contrib/create-pr/SKILL.md b/skills-contrib/create-pr/SKILL.md index 8634ebf297af..bd005dab68b2 100644 --- a/skills-contrib/create-pr/SKILL.md +++ b/skills-contrib/create-pr/SKILL.md @@ -69,11 +69,13 @@ The PR description must follow a **decision-led, narrative** structure. A teamma #### Consult the PR template -Read `.github/PULL_REQUEST_TEMPLATE.md` once before drafting. The template's required headers (in prisma-next today: `## Linked issue`, `## Testing performed`, `## Checklist`) must appear in the final body even when the skill's recommended structure below doesn't list them. Where the template and the skill overlap, use the template's richer header (e.g. `## Linked issue` — with a `Refs:` link and any prerequisite-PR / follow-up-PR context — replaces the bare close-line at the top). +Read `.github/PULL_REQUEST_TEMPLATE.md` once before drafting. The template's required headers (today: `## Linked issue`, `## Summary`, `## Testing performed`, `## Skill update`, `## Checklist`, `## Notes for the reviewer`) must appear in the final body even when the skill's recommended structure below doesn't list them. Where the template and the skill overlap, use the template's richer header (e.g. `## Linked issue` — with a `Refs:` link and any prerequisite-PR / follow-up-PR context — replaces the bare close-line at the top). #### Required structure (in this order) -1. **`## Linked issue`** — the template header, used instead of a bare close-line. Single `Refs [$TICKET_ID](https://linear.app/...)` link plus, if relevant, links to any prerequisite or follow-up PRs and the Linear tickets they close. Keep it short — three lines max. +1. **`## Linked issue`** — the template header, used instead of a bare close-line. The template asks for a GitHub issue here; a maintainer PR puts the Linear ticket in the same place: a single `Refs [$TICKET_ID](https://linear.app/...)` link, plus `Fixes #N` as well when a GitHub issue exists, plus links to any prerequisite or follow-up PRs and the Linear tickets they close. Keep it short — three lines max. + + **`## Skill update`** — name the agent skill the change teaches, or write `n/a — internal only`. The template checklist asks you to confirm this section, so a body without it cannot tick that box truthfully. 2. **`## At a glance`** — a copy-pasteable code sample from real code in the branch (not invented, not pseudocode) that demonstrates the change in user-observable terms. Below the code, one short sentence that grounds the "before" state if relevant. @@ -125,7 +127,7 @@ Read `.github/PULL_REQUEST_TEMPLATE.md` once before drafting. The template's req #### Drafting workflow -1. Run the `.agents/skills/drive-pr-walkthrough/SKILL.md` workflow for the current branch vs base (default: `origin/main...HEAD`) and write `walkthrough.md` to disk. The walkthrough provides raw material — narrative steps, behavior changes, evidence links — but its default section order is **not** the PR shape. You will restructure it. +1. Run the `drive-pr-walkthrough` skill for the current branch vs base (default: `origin/main...HEAD`) and write `walkthrough.md` to disk. That skill installs from [prisma/ignite](https://github.com/prisma/ignite) and is not part of this repo; if it is not installed, derive the walkthrough from the diff yourself. The walkthrough provides raw material — narrative steps, behavior changes, evidence links — but its default section order is **not** the PR shape. You will restructure it. 2. Write the PR body to disk as a working file (e.g. `wip/pr--body.md`) following the **Required structure** above. Reuse the walkthrough's narrative, behavior bullets, and evidence links where they fit; restructure to lead with the code sample and the decision, and to end with alternatives. 3. **Adjust links for GitHub**: - Keep helpful link text (file paths, optionally line ranges). diff --git a/skills-contrib/draft-release-notes/SKILL.md b/skills-contrib/draft-release-notes/SKILL.md index 03bec72dede2..268d76d5649b 100644 --- a/skills-contrib/draft-release-notes/SKILL.md +++ b/skills-contrib/draft-release-notes/SKILL.md @@ -121,16 +121,16 @@ Write the entries under the fixed section order from [`docs/releases/README.md`] 3. **Fixes** — bug fixes. 4. **New contributors** — first-time contributors, with the PR that welcomed them. -Breaking changes lead because they are what a reader scanning the notes most needs to see. Every line links its PR as an **absolute markdown link** — `[#NNN](https://github.com/prisma/prisma-next/pull/NNN)`, never bare `#NNN`. Bare references only autolink inside the GitHub Release body; they render as plain text when the committed `docs/releases/v.md` is read as a repo file or in PR review, so the explicit link form is what makes every reference work in every context. +Breaking changes lead because they are what a reader scanning the notes most needs to see. Every line links its PR as an **absolute markdown link** — `[#NNN](https://github.com/prisma/prisma/pull/NNN)`, never bare `#NNN`. Bare references only autolink inside the GitHub Release body; they render as plain text when the committed `docs/releases/v.md` is read as a repo file or in PR review, so the explicit link form is what makes every reference work in every context. ### 6. Anchor breaking-change entries to their migration recipe -A breaking change shipping in this release has a matching upgrade-instructions directory keyed to the minor transition, following the convention enforced by [`scripts/check-upgrade-coverage.mjs`](../../scripts/check-upgrade-coverage.mjs) and authored via [`record-upgrade-instructions`](../record-upgrade-instructions/SKILL.md). The transition label is `.-to-.` — computed from the **previous stable tag's** minor and `$NEXT`'s minor (e.g. `v0.11.0` → `0.12.0` gives `0.11-to-0.12`). Point the breaking note at the recipe directory rather than restating the migration. +A breaking change shipping in this release has a matching upgrade-instructions directory keyed to the minor transition, following the convention enforced by [`scripts/check-upgrade-coverage.mjs`](../../scripts/check-upgrade-coverage.mjs) and authored via [`record-upgrade-instructions`](../record-upgrade-instructions/SKILL.md). The transition label — written `` below — names both ends of the hop, each end rendered the way `versionSegment()` in [`scripts/check-upgrade-coverage.mjs`](../../scripts/check-upgrade-coverage.mjs) renders it: a stable version truncates to `major.minor` (`v0.11.0` → `0.12.0` gives `0.11-to-0.12`), and a prerelease keeps its full version string (`8.0.0-rc.1-to-8.0.0-rc.2`). Point the breaking note at the recipe directory rather than restating the migration. **Recipe links must be absolute, tag-pinned URLs** — `https://github.com/prisma/prisma/blob/v$NEXT/...`. The notes file becomes the GitHub Release body via `--notes-file`, and the Release page does **not** reliably resolve repo-relative links, so a relative recipe path would publish as a dead migration link. Pinning to the release tag (`/blob/v$NEXT/`) means the link always resolves and never rots as the recipe tree evolves on `main`: -- User-facing migrations: `https://github.com/prisma/prisma/blob/v$NEXT/skills/upgrade/prisma-next-upgrade/upgrades/-to-/` -- Extension-author migrations: `https://github.com/prisma/prisma/blob/v$NEXT/skills/extension-author/prisma-8-extension-upgrade/upgrades/-to-/` +- User-facing migrations: `https://github.com/prisma/prisma/blob/v$NEXT/skills/prisma-next-upgrade/upgrades//` +- Extension-author migrations: `https://github.com/prisma/prisma/blob/v$NEXT/skills/prisma-8-extension-upgrade/upgrades//` A breaking change can affect one or both audiences — link whichever recipe directories exist. @@ -142,7 +142,7 @@ For a **skipped-publish range** (more than one minor in this release — see gra Prose tells a reader *that* something changed; a short before/after snippet shows them *what it looks like*, which is what they actually need to act. For the most code-visible breaking changes — contract-shape changes, authoring-surface changes, runtime-option or builder-API changes — nest a compact `before` / `after` example under the prose bullet. -- **Source it from the recipe, don't invent it.** The matching `-to-` upgrade recipe (authored via [`record-upgrade-instructions`](../record-upgrade-instructions/SKILL.md)) already contains authoritative before/after migration code — lift the snippet from there so it stays accurate. If the change is only visible in the emitted `contract.json` / `contract.d.ts`, a minimal shape diff from the recipe or the PR diff is fine. +- **Source it from the recipe, don't invent it.** The matching `` upgrade recipe (authored via [`record-upgrade-instructions`](../record-upgrade-instructions/SKILL.md)) already contains authoritative before/after migration code — lift the snippet from there so it stays accurate. If the change is only visible in the emitted `contract.json` / `contract.d.ts`, a minimal shape diff from the recipe or the PR diff is fine. - **Keep it tight.** A few lines before, a few lines after — enough to show the shape, not the whole file. - **Lead with PSL.** When the change is on the authoring surface, write the example in PSL (```` ```prisma ````, never ```` ```psl ````), per the repo's authoring-surface convention. Use TS or JSON only when the change is genuinely a TS-surface change (a builder/runtime option, a consumer reading the emitted `.d.ts`) or an emitted-shape change with no PSL form. - **Skip operational-only breaks.** Version-floor bumps, peer-dependency changes, and package removals/extractions have no illuminating code diff — prose suffices for those. @@ -150,7 +150,7 @@ Prose tells a reader *that* something changed; a short before/after snippet show The format is the prose bullet, then the nested example: ````md -- **** — <what changed and what the reader must do; recipe link>. ([#<pr>](https://github.com/prisma/prisma-next/pull/<pr>)) +- **<title>** — <what changed and what the reader must do; recipe link>. ([#<pr>](https://github.com/prisma/prisma/pull/<pr>)) Before: @@ -170,7 +170,7 @@ The format is the prose bullet, then the nested example: Preserve the "New contributors" credit that `--generate-notes` gave for free. Each first-time contributor gets a line naming the PR that welcomed them, with both the handle and the PR as absolute links: ```md -- [@<handle>](https://github.com/<handle>) made their first contribution in [#<pr>](https://github.com/prisma/prisma-next/pull/<pr>) +- [@<handle>](https://github.com/<handle>) made their first contribution in [#<pr>](https://github.com/prisma/prisma/pull/<pr>) ``` Resolve first-time status from PR author metadata (e.g. `gh api` `author_association` of `FIRST_TIME_CONTRIBUTOR` / `FIRST_TIMER`, or by checking whether the author appears in the range before this PR). @@ -186,7 +186,7 @@ Fill the [`docs/releases/README.md`](../../docs/releases/README.md) template int ## Breaking changes -- **<short title>** — <what changed and what the reader must do; link the upgrade recipe>. ([#<pr>](https://github.com/prisma/prisma-next/pull/<pr>)) +- **<short title>** — <what changed and what the reader must do; link the upgrade recipe>. ([#<pr>](https://github.com/prisma/prisma/pull/<pr>)) Before: @@ -202,15 +202,15 @@ Fill the [`docs/releases/README.md`](../../docs/releases/README.md) template int ## Features -- <new capability>. ([#<pr>](https://github.com/prisma/prisma-next/pull/<pr>)) +- <new capability>. ([#<pr>](https://github.com/prisma/prisma/pull/<pr>)) ## Fixes -- <bug fix>. ([#<pr>](https://github.com/prisma/prisma-next/pull/<pr>)) +- <bug fix>. ([#<pr>](https://github.com/prisma/prisma/pull/<pr>)) ## New contributors -- [@<handle>](https://github.com/<handle>) made their first contribution in [#<pr>](https://github.com/prisma/prisma-next/pull/<pr>) +- [@<handle>](https://github.com/<handle>) made their first contribution in [#<pr>](https://github.com/prisma/prisma/pull/<pr>) ```` Then **prepend** a `## v$NEXT` entry to [`CHANGELOG.md`](../../CHANGELOG.md), mirroring the notes-file body (newest-first). The CHANGELOG is a plain newest-first mirror — no second authoring format, no "Keep a Changelog" headers; copy the section bodies under the `## v$NEXT` header at the top of the entry list (below the file's intro and the `<!-- New release entries go here … -->` marker). @@ -250,8 +250,8 @@ Cutting `v0.12.0` from `origin/main` (previous stable tag `v0.11.0`). 3. PR #1240's title is `TML-2536: contract deserializer seam`. Read TML-2536 in Linear → the user-facing outcome is "contract deserialization now goes through an explicit adapter seam". Write that outcome in public words; cite #1240, not TML-2536. 4. Triage: #1240 changes the contract format → **always-include, breaking**. A CI-cache tweak (#1237) and a test-only refactor (#1239) → **default-exclude**, dropped silently. A new `includeMany` capability (#1234) → feature. A null-handling bug fix (#1242) → fix. First-time contributor @somebody on #1238. 5. Categorize: Breaking changes (#1240) → Features (#1234) → Fixes (#1242) → New contributors (@somebody, #1238). -6. The breaking change's transition is `0.11-to-0.12`. The recipe dir `skills/upgrade/prisma-next-upgrade/upgrades/0.11-to-0.12/` exists in the checkout → the breaking note links it as a tag-pinned URL, `https://github.com/prisma/prisma/blob/v0.12.0/skills/upgrade/prisma-next-upgrade/upgrades/0.11-to-0.12/`. (If it were absent, the note would describe the required adapter migration inline instead.) -7. #1240 is a code-visible contract-shape/runtime change, so it earns a before/after example — lifted from the `0.11-to-0.12` recipe (a TS runtime change, so a `ts` fence). @somebody's contributor line, with absolute links: `- [@somebody](https://github.com/somebody) made their first contribution in [#1238](https://github.com/prisma/prisma-next/pull/1238)`. +6. The breaking change's transition is `0.11-to-0.12`. The recipe dir `skills/prisma-next-upgrade/upgrades/0.11-to-0.12/` exists in the checkout → the breaking note links it as a tag-pinned URL, `https://github.com/prisma/prisma/blob/v0.12.0/skills/prisma-next-upgrade/upgrades/0.11-to-0.12/`. (If it were absent, the note would describe the required adapter migration inline instead.) +7. #1240 is a code-visible contract-shape/runtime change, so it earns a before/after example — lifted from the `0.11-to-0.12` recipe (a TS runtime change, so a `ts` fence). @somebody's contributor line, with absolute links: `- [@somebody](https://github.com/somebody) made their first contribution in [#1238](https://github.com/prisma/prisma/pull/1238)`. 8. Write `docs/releases/v0.12.0.md` (every PR ref + handle an absolute link; the breaking entry carries a before/after): ````md @@ -261,7 +261,7 @@ Contract deserialization gains an explicit adapter seam, and queries can now eag ## Breaking changes -- **Contract deserialization requires an adapter seam** — deserialization now goes through an explicit seam adapter; existing code must register one. See the [0.11-to-0.12 upgrade recipe](https://github.com/prisma/prisma-next/blob/v0.12.0/skills/upgrade/prisma-next-upgrade/upgrades/0.11-to-0.12/). ([#1240](https://github.com/prisma/prisma-next/pull/1240)) +- **Contract deserialization requires an adapter seam** — deserialization now goes through an explicit seam adapter; existing code must register one. See the [0.11-to-0.12 upgrade recipe](https://github.com/prisma/prisma/blob/v0.12.0/skills/prisma-next-upgrade/upgrades/0.11-to-0.12/). ([#1240](https://github.com/prisma/prisma/pull/1240)) Before: @@ -277,15 +277,15 @@ Contract deserialization gains an explicit adapter seam, and queries can now eag ## Features -- `includeMany` eager-loads related records in a single query. ([#1234](https://github.com/prisma/prisma-next/pull/1234)) +- `includeMany` eager-loads related records in a single query. ([#1234](https://github.com/prisma/prisma/pull/1234)) ## Fixes -- Null values in `returning()` projections no longer throw. ([#1242](https://github.com/prisma/prisma-next/pull/1242)) +- Null values in `returning()` projections no longer throw. ([#1242](https://github.com/prisma/prisma/pull/1242)) ## New contributors -- [@somebody](https://github.com/somebody) made their first contribution in [#1238](https://github.com/prisma/prisma-next/pull/1238) +- [@somebody](https://github.com/somebody) made their first contribution in [#1238](https://github.com/prisma/prisma/pull/1238) ```` Then prepend the same body under `## v0.12.0` to `CHANGELOG.md`. @@ -297,7 +297,7 @@ Contract deserialization gains an explicit adapter seam, and queries can now eag - [`docs/releases/README.md`](../../docs/releases/README.md) — the committed-notes-file convention, the no-fallback design, the section order, and the template this skill fills. - [`CHANGELOG.md`](../../CHANGELOG.md) — the rolling newest-first mirror this skill prepends. - [`publish-npm-version`](../publish-npm-version/SKILL.md) — the release-cut skill that invokes this one from the `release/<version>` worktree. -- [`record-upgrade-instructions`](../record-upgrade-instructions/SKILL.md) — the breaking-change upgrade-recipe authoring flow whose `upgrades/<prev.minor>-to-<head.minor>/` directories the breaking-change section anchors to. +- [`record-upgrade-instructions`](../record-upgrade-instructions/SKILL.md) — the breaking-change upgrade-recipe authoring flow whose `upgrades/<transition-label>/` directories the breaking-change section anchors to. - [`scripts/check-upgrade-coverage.mjs`](../../scripts/check-upgrade-coverage.mjs) — the transition-label convention (`<major>.<minor>-to-<major>.<minor>`) and skipped-publish chain handling. - [`docs/oss/versioning.md`](../../docs/oss/versioning.md) — the version contract and release procedure these notes are part of. - Linear ticket: [TML-2758](https://linear.app/prisma-company/issue/TML-2758). diff --git a/skills-contrib/github-review-iteration/SKILL.md b/skills-contrib/github-review-iteration/SKILL.md index 32c096fdaf6d..55c9c046fdb5 100644 --- a/skills-contrib/github-review-iteration/SKILL.md +++ b/skills-contrib/github-review-iteration/SKILL.md @@ -25,6 +25,8 @@ This skill depends on three sibling skills that live **in the same parent direct All script paths in this document are **relative to this skill's directory**. Use `../` to reach sibling skills. Do **not** search the workspace/repo for these files — they are part of the skills installation, not the project being reviewed. +**Run the scripts from the repository root**, addressing them by their full path under the skills installation. The reviews root defaults to `wip/reviews` resolved against the working directory, so a run started elsewhere writes artifacts outside the repo-root `wip/` tree that `.gitignore` covers. Pass `--reviews-root <repo-root>/wip/reviews` if you must run from another directory. + ## Usage This skill supports subcommands: @@ -36,7 +38,7 @@ This skill supports subcommands: /github-review-iteration iterate <PR_URL> [output-dir] ``` -When `output-dir` is omitted, use the standard layout: `wip/reviews/<owner>_<repo>_pr-<number>/` (derived from PR URL). +When `output-dir` is omitted, use the standard layout: `wip/reviews/<owner>_<repo>_pr-<number>/` (derived from the PR URL, with owner and repo lowercased — derive a directory name by hand the same way, or the artifacts split across two directories). Example: diff --git a/skills-contrib/psl-ast-layers/SKILL.md b/skills-contrib/psl-ast-layers/SKILL.md index 42de9e3b7f5d..4aba602832ef 100644 --- a/skills-contrib/psl-ast-layers/SKILL.md +++ b/skills-contrib/psl-ast-layers/SKILL.md @@ -18,7 +18,7 @@ The PSL parser (`packages/1-framework/2-authoring/psl-parser`) produces a three- | Red tree | `SyntaxNode`, `SyntaxToken` (`syntax/red.ts`, `syntax/navigation.ts`) | Navigation with offsets and parents: `findAncestor()`, `tokenAtOffset()`, `nextToken`/`prevToken`, `nonTriviaSibling()` | Navigation *outside* the current node | | Typed AST | `ModelDeclarationAst`, `FieldDeclarationAst`, … (`syntax/ast/`) | Structural information about a *known* node via getters (`name()`, `fields()`, `lbrace()`, `value()`) | **Default choice** | -Everything is exported from `@internal/psl-parser/syntax` (and re-exported from the package root). `parse(source)` returns `{ document: DocumentAst, diagnostics, sourceFile }` — you start in the typed layer. +Everything is exported from `@internal/psl-parser/syntax`. `parse(source)` returns `{ document: DocumentAst, diagnostics, sourceFile }` — you start in the typed layer. ## Choosing a layer diff --git a/skills-contrib/publish-npm-version/SKILL.md b/skills-contrib/publish-npm-version/SKILL.md index a486b174f98e..613f9f5d53c7 100644 --- a/skills-contrib/publish-npm-version/SKILL.md +++ b/skills-contrib/publish-npm-version/SKILL.md @@ -26,10 +26,10 @@ Read [`docs/oss/versioning.md`](../../docs/oss/versioning.md) before running thi - The lockstep guarantee (every workspace package matches the root). - The v8 RC line (`8.0.0-rc.N`, `latest` frozen until `8.0.0` final). - The dist-tag convention (`latest` / `dev` / `beta`). -- The full release procedure (this skill is step 2 of 3; merging the PR is the publish trigger — there is no separate dispatch step). +- The full release procedure (this skill covers steps 1-2 of 3; merging the PR is the publish trigger — there is no separate dispatch step). - The emergency-patch path (this skill does **not** handle patches). -This SKILL.md covers only the mechanics of step 2 — opening the bump PR. +This SKILL.md covers steps 1-2 — opening the bump PR and driving the release notes. Merging (step 3) stays the human gate. ## Pre-flight @@ -99,7 +99,7 @@ If either precondition is unmet, stop and surface the issue. Do **not** try to a 9. **Open the PR** with `gh pr create`. Use the title: ```text - Bump to version <version> + chore(release): bump to <version> ``` The body should: diff --git a/skills-contrib/record-gotcha/SKILL.md b/skills-contrib/record-gotcha/SKILL.md index 9a0796be612d..c7769d06a534 100644 --- a/skills-contrib/record-gotcha/SKILL.md +++ b/skills-contrib/record-gotcha/SKILL.md @@ -49,7 +49,7 @@ This skill **requires** the Linear MCP plugin to be installed and authenticated. **If the Linear MCP plugin is not available or not authenticated, halt and tell the operator** something like: -> I just hit a gotcha I'd like to record, but the Linear MCP plugin isn't available. Please install and authenticate `plugin-linear-linear` (the [Linear plugin for Cursor](https://cursor.com/plugins/linear)), then re-run the request. The skill needs to file a Triage-state ticket in the matching Prisma gotchas project. +> I just hit a gotcha I'd like to record, but the Linear MCP plugin isn't available. Please install and authenticate the Linear MCP plugin (`plugin:linear:linear` in Claude Code; the [Linear plugin for Cursor](https://cursor.com/plugins/linear)), then re-run the request. The skill needs to file a Triage-state ticket in the matching Prisma gotchas project. Do not proceed. Do not write the file entry without the ticket. The two halves are intentionally coupled — the file is the local record; the ticket is the team's signal. Both must exist for the pipeline to work. @@ -120,7 +120,7 @@ Numbered, in order. Don't skip steps; the value comes from doing all of them. ### 1. Verify Linear MCP is available -If the `plugin-linear-linear` MCP isn't installed or isn't authenticated, halt per § Hard prerequisite. +If the Linear MCP plugin isn't installed or isn't authenticated, halt per § Hard prerequisite. ### 2. Identify the product @@ -281,7 +281,7 @@ Each entry is also filed as a Triage-state Linear ticket in the matching gotchas - Prisma Compute → [`compute-gotchas`](https://linear.app/prisma-company/project/compute-gotchas-dd3ac34b5ad4/overview) - Prisma Postgres → [`ppg-gotchas`](https://linear.app/prisma-company/project/ppg-gotchas-afe77336f696/overview) -The capture workflow is documented in [`.agents/skills/record-gotcha/SKILL.md`](.agents/skills/record-gotcha/SKILL.md). +The capture workflow is documented in [`.agents/skills/record-gotchas/SKILL.md`](.agents/skills/record-gotchas/SKILL.md). --- diff --git a/skills-contrib/review-implement-phase/SKILL.md b/skills-contrib/review-implement-phase/SKILL.md index eb21c1c74fc8..f65917ccf285 100644 --- a/skills-contrib/review-implement-phase/SKILL.md +++ b/skills-contrib/review-implement-phase/SKILL.md @@ -33,7 +33,7 @@ System dependencies required on PATH: - `gh` (GitHub CLI) -If `gh` is missing, halt immediately and ask the user to install it. The implement-phase scripts no longer depend on `jq`. +If `gh` is missing, halt immediately and ask the user to install it. The implement-phase scripts require only `gh`. GitHub admin capability must be available before starting implementation: @@ -62,7 +62,8 @@ If missing, instruct user to run: - thread replies via `addPullRequestReviewThreadReply` (or wrapper script) - issue comments via `addComment` (or wrapper script) - Before starting implementation: - - **Detect pending reviews authored by the acting user** on this PR. + - **Detect pending reviews authored by the acting user** on this PR: + `gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$pr){reviews(last:20,states:PENDING){nodes{id author{login}}}}}}' -F owner=<owner> -F repo=<repo> -F pr=<number>` - If any exist, **halt** and clean them up (submit or dismiss) before continuing. - After posting any "On it" / "Done" comment: - **Re-check for pending reviews authored by the acting user**. diff --git a/skills-contrib/review-implement-phase/agents/review-implementer.md b/skills-contrib/review-implement-phase/agents/review-implementer.md index 5789e9a00b5b..d88ce0d08928 100644 --- a/skills-contrib/review-implement-phase/agents/review-implementer.md +++ b/skills-contrib/review-implement-phase/agents/review-implementer.md @@ -3,7 +3,6 @@ name: review-implementer description: Implements a PR’s review action list, commits in small logical steps, and resolves GitHub review threads with “Done” replies when finished. Use when review-actions.md exists for a PR. tools: Write, Read, Bash, WebFetch color: red -model: GPT-5.3 Codex --- You are a PR **review implementer**. Your job is to turn an action plan from review triage into code changes that get the PR merged. @@ -27,7 +26,7 @@ Run commands from the `review-implement-phase` skill directory. Script paths bel 3. For each action: - Make the smallest coherent change. - Run the smallest relevant checks (package test/typecheck/lint as appropriate). - - Create a focused commit (explicit staging; no `git add -A` / `git add .`; no amend). + - Create a focused commit (explicit staging; no `git add -A` / `git add .`; no amend). The commit steps need a git checkout; in a Jujutsu workspace, run them from a colocated checkout or use the equivalent `jj` commands. - Reply on the associated GitHub thread when you begin work (short “On it” + 👍) using: - `node ./scripts/post-review-thread-reply.mjs --repo <owner>/<repo> --pr <number> --comment-node-id <primaryCommentNodeId> --body "<text>"` - For `pull_request_review` targets (review-body findings, `PRR_…` node ids), the helper auto-detects the kind and posts a top-level PR issue comment (response `kind: "issue_comment"`). There is no inline thread, so **skip `resolve-review-thread.mjs`** for these targets and record the issue-comment id in the action's `done` record (`done.githubAdmin.issueCommentId`). diff --git a/skills-contrib/review-triage-phase/SKILL.md b/skills-contrib/review-triage-phase/SKILL.md index 13665a249074..d8c311e4812a 100644 --- a/skills-contrib/review-triage-phase/SKILL.md +++ b/skills-contrib/review-triage-phase/SKILL.md @@ -37,7 +37,7 @@ If `review-state.json` is missing, instruct user to run: - `/review-fetch-phase <PR_URL> [output-dir]` Note: -- `review-actions.json` scaffolding is generated from `review-state.targets`, which now includes unresolved review threads, review bodies, and issue comments. +- `review-actions.json` scaffolding is generated from `review-state.targets`, taking the thread and review-body targets. Issue-comment targets are captured in `review-state.json` but get no scaffolded action. - **Compound review bodies**: A single `pull_request_review` target may contain multiple distinct findings (e.g., CodeRabbit bundles "outside diff range" comments, actionable comments, and nitpicks into one review body). The triager must decompose these into individual action items during triage — never blanket-dismiss a review body without reading its content. ## Behavior diff --git a/skills-contrib/review-triage-phase/agents/review-triager.md b/skills-contrib/review-triage-phase/agents/review-triager.md index 2451b71c2306..9a8b172553e5 100644 --- a/skills-contrib/review-triage-phase/agents/review-triager.md +++ b/skills-contrib/review-triage-phase/agents/review-triager.md @@ -3,7 +3,6 @@ name: review-triager description: Triage GitHub PR review threads into an action plan and administer threads (reply/react/resolve) with an implementer’s pragmatism. Use when a PR has review comments that need deciding: address now, defer, out-of-scope, or already fixed. tools: Write, Read, Bash, WebFetch color: orange -model: GPT-5.2 --- You are a **review triager**: an implementer-focused reviewer responsible for shepherding a PR through iterative GitHub review. @@ -61,11 +60,11 @@ You do **not** implement code changes in this role. You **decide what to do** by 4. **Administer GitHub threads** - For **WILL ADDRESS**: - Reply: acknowledge + state intention to address. - - React with 👍. + - React with 👍: `gh api graphql -f query='mutation { addReaction(input: {subjectId: "<comment-node-id>", content: THUMBS_UP}) { reaction { content } } }'`. - Leave the thread **unresolved**. - For everything else: - Reply: explain politely and concretely why it will not be addressed now (or how it will be deferred). - - React with 👎 if it will not be addressed in this PR (use sparingly but consistently). + - React with 👎 if it will not be addressed in this PR (use sparingly but consistently): the same mutation with `content: THUMBS_DOWN`. - Resolve the thread when appropriate (outdated/out-of-scope/not-addressed). - For **DEFER** specifically: - Create a Linear follow-up issue (group related deferred comments where logical). @@ -116,9 +115,11 @@ Status: <Triaged | In progress | Complete> All actions are listed below by default (the renderer's `--view all` mode); pass `--view will-address` to limit the table to actions triaged as **WILL ADDRESS**. -| Action ID | Decision | Target | Link | Action | Linear | Target files | Acceptance check | Status | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | -| A01_PRRT_xxx | defer | review_thread / PRRT_xxx | <link> | <what to change> | TML-1916 | <paths> | <how to know it’s done> | pending | +| Action ID | Decision | Target | Link | Action | Target files | Acceptance check | Status | +| --- | --- | --- | --- | --- | --- | --- | --- | +| A01_PRRT_xxx | defer | review_thread / PRRT_xxx | <link> | <what to change> | <paths> | <how to know it’s done> | pending | + +The deferred ticket lives in the JSON as `linearIssue`; the rendered table has no Linear column. ``` ## Constraints diff --git a/skills-contrib/write-architecture-docs/SKILL.md b/skills-contrib/write-architecture-docs/SKILL.md index b64512370b3c..8f657cbe8cd8 100644 --- a/skills-contrib/write-architecture-docs/SKILL.md +++ b/skills-contrib/write-architecture-docs/SKILL.md @@ -46,7 +46,7 @@ Bad: "MongoDB is a database family in Prisma Next. The contract, ORM, execution **Inline summaries with ADR links.** When referencing an ADR, summarize the key idea in the text and link the ADR for depth. The doc should be understandable without following any links. -Good: "An owned model declares `owner: \"User\"` — a domain fact about aggregate membership. Its data lives within the owner's storage. See [ADR 177](docs/architecture%20docs/adrs/ADR%20177%20-%20Ownership%20replaces%20relation%20strategy.md)." +Good: "An owned model declares `owner: \"User\"` — a domain fact about aggregate membership. Its data lives within the owner's storage. See [ADR 177](../adrs/ADR%20177%20-%20Ownership%20replaces%20relation%20strategy.md)." Bad: "See [ADR 177](...) for how embedding works." **References section.** Organize by durability: From 6f9eae34e126e9267709f53c45a42eecd0a8d463 Mon Sep 17 00:00:00 2001 From: Oleksii Orlenko <robot@aqrln.net> Date: Thu, 20 Aug 2026 15:44:40 +0200 Subject: [PATCH 2/4] docs(skills): apply review fixes to the skills-audit doc corrections (TML-3223) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/releases/README.md: link both the user and the extension-author recipe directories. - contrib-pr: name prisma/prisma in the trigger examples; reserve "n/a — internal only" for internal or refactor changes. - create-pr: same skill-update wording; cite the documented ignite install command in the not-installed fallback. - draft-release-notes: say what to do when no recipe directory exists. - github-review-iteration: make the wrapper example runnable from the repository root and say how to prefix the sibling-relative paths. - review-implement-phase: filter the pending-review query by the acting user, and note the one-per-user limit and how to page. - write-architecture-docs: say the ADR link is relative to the subsystem doc being written. Claude-Session: https://claude.ai/code/session_01NnNjsNcPMtbJZhnZz5Zzbe Signed-off-by: Oleksii Orlenko <robot@aqrln.net> --- docs/releases/README.md | 4 +++- skills-contrib/contrib-pr/SKILL.md | 8 ++++---- skills-contrib/create-pr/SKILL.md | 4 ++-- skills-contrib/draft-release-notes/SKILL.md | 1 + skills-contrib/github-review-iteration/SKILL.md | 4 +++- skills-contrib/review-implement-phase/SKILL.md | 10 ++++++---- skills-contrib/write-architecture-docs/SKILL.md | 2 +- 7 files changed, 20 insertions(+), 13 deletions(-) diff --git a/docs/releases/README.md b/docs/releases/README.md index 02220586b376..fa9e7b23abaf 100644 --- a/docs/releases/README.md +++ b/docs/releases/README.md @@ -18,7 +18,9 @@ These files are drafted automatically by the [`draft-release-notes`](../../skill - **Lead with breaking changes** — they are what a reader scanning the notes most needs to see. - **Show the impact of breaking changes with a short before/after example.** For the code-visible breaking changes (contract-shape changes, authoring-surface changes, runtime-option changes), nest a compact `before` / `after` snippet under the prose bullet so a reader can see the change at a glance. Source the snippet from the matching `<transition-label>` upgrade recipe so it stays accurate. Lead with PSL (```` ```prisma ````) when the change is on the authoring surface; use TS/JSON only when the change is genuinely a TS/emitted-shape change. Operational-only breaks (version floors, peer-dep changes, package removals) need no example. - **Link PRs and contributors as absolute markdown links** — `[#1234](https://github.com/prisma/prisma/pull/1234)` and `[@handle](https://github.com/handle)`, never bare `#1234` / `@handle`. Bare references only autolink inside the GitHub Release body, **not** when this file is read as a repo file or in PR review; explicit links work in every context. Attribute contributors, especially first-time ones. -- **Link migration recipes as absolute, tag-pinned URLs** — `https://github.com/prisma/prisma/blob/v<version>/skills/prisma-next-upgrade/upgrades/<transition-label>/` — not repo-relative paths. This file is published verbatim as the GitHub Release body, where repo-relative links do not resolve; pinning to the release tag keeps the link working and rot-proof. +- **Link migration recipes as absolute, tag-pinned URLs** — not repo-relative paths. This file is published verbatim as the GitHub Release body, where repo-relative links do not resolve; pinning to the release tag keeps the link working and rot-proof. A breaking change can affect either audience or both, so link whichever recipe directories exist: + - User-facing migrations: `https://github.com/prisma/prisma/blob/v<version>/skills/prisma-next-upgrade/upgrades/<transition-label>/` + - Extension-author migrations: `https://github.com/prisma/prisma/blob/v<version>/skills/prisma-8-extension-upgrade/upgrades/<transition-label>/` The section order is: **Breaking changes → Features → Fixes → New contributors**. diff --git a/skills-contrib/contrib-pr/SKILL.md b/skills-contrib/contrib-pr/SKILL.md index 3db27d56b44b..b7f9436360a3 100644 --- a/skills-contrib/contrib-pr/SKILL.md +++ b/skills-contrib/contrib-pr/SKILL.md @@ -14,8 +14,8 @@ If the user is a maintainer with access to internal Linear tickets, use `create- Trigger this skill when the user says any of: - "Open a PR for this contribution" -- "Submit this as a PR to prisma-next" -- "I'm contributing to prisma-next, finalize my change" +- "Submit this as a PR to prisma/prisma" +- "I'm contributing to Prisma Next, finalize my change" - "Help me get this PR ready for review" If the user has clearly already followed the contribution flow and just needs the `gh pr create` invocation, you may skip directly to step 5. @@ -51,7 +51,7 @@ Before opening the PR, check: - **One logical change.** If the diff includes unrelated cleanup or "while I was here" fixes, ask the user whether to split them into separate PRs. Mixed-scope PRs almost always trigger a "please split this" review comment. - **Substantive change?** If the change is more than a typo / doc fix / obvious bug fix, ask the user whether they opened a tracking issue first per `CONTRIBUTING.md`. If not, recommend they do — maintainers will respond within 5 business days, and a half-day issue conversation can prevent a one-week PR rewrite when the design direction differs from what they expect. - **Tests updated.** If the change has any behavioural delta and there are no test changes in the diff, push back on the user before opening the PR. "Why aren't there tests?" is the most common reason a PR gets bounced. -- **No backward-compat shims.** prisma-next is pre-1.0; if the change renames or removes an API, the call sites should be updated, not aliased. +- **No backward-compat shims.** Prisma Next is pre-1.0; if the change renames or removes an API, the call sites should be updated, not aliased. ### Step 3 — Run the right test suites @@ -123,7 +123,7 @@ Fill in the [pull request template](../../.github/PULL_REQUEST_TEMPLATE.md) sect - **Linked issue**: `Fixes #N` / `Refs #N`. If no issue exists because the change is small, write `n/a — small change`. - **Summary**: one or two sentences focused on *why*, not file-by-file *what*. "Adds X because Y was broken" rather than "Adds X function in foo.ts and modifies bar.ts". - **Testing performed**: list the actual `pnpm test:*` commands you ran. If you ran a manual repro (e.g. against the demo), say so. -- **Skill update**: say which agent skill the change teaches, or write `n/a — internal only` when the change touches nothing an agent skill describes. The checklist below asks you to confirm this section. +- **Skill update**: say which agent skill the change teaches. Write `n/a — internal only` only when the change is purely internal or a refactor with no user-visible delta. A user-facing change that teaches no existing skill still needs a sentence saying why no skill update is required. The checklist below asks you to confirm this section. - **Checklist**: confirm DCO signoff, scope, tests, conventional title. - **Notes for the reviewer** (optional): alternative approaches you considered, follow-ups intentionally deferred, anything you want the reviewer to focus on. diff --git a/skills-contrib/create-pr/SKILL.md b/skills-contrib/create-pr/SKILL.md index bd005dab68b2..a99ec97f27c4 100644 --- a/skills-contrib/create-pr/SKILL.md +++ b/skills-contrib/create-pr/SKILL.md @@ -75,7 +75,7 @@ Read `.github/PULL_REQUEST_TEMPLATE.md` once before drafting. The template's req 1. **`## Linked issue`** — the template header, used instead of a bare close-line. The template asks for a GitHub issue here; a maintainer PR puts the Linear ticket in the same place: a single `Refs [$TICKET_ID](https://linear.app/...)` link, plus `Fixes #N` as well when a GitHub issue exists, plus links to any prerequisite or follow-up PRs and the Linear tickets they close. Keep it short — three lines max. - **`## Skill update`** — name the agent skill the change teaches, or write `n/a — internal only`. The template checklist asks you to confirm this section, so a body without it cannot tick that box truthfully. + **`## Skill update`** — name the agent skill the change teaches. Reserve `n/a — internal only` for changes that are purely internal or a refactor with no user-visible delta; a user-facing change that teaches no existing skill still needs a sentence saying why no update is required. The template checklist asks you to confirm this section, so a body without it cannot tick that box truthfully. 2. **`## At a glance`** — a copy-pasteable code sample from real code in the branch (not invented, not pseudocode) that demonstrates the change in user-observable terms. Below the code, one short sentence that grounds the "before" state if relevant. @@ -127,7 +127,7 @@ Read `.github/PULL_REQUEST_TEMPLATE.md` once before drafting. The template's req #### Drafting workflow -1. Run the `drive-pr-walkthrough` skill for the current branch vs base (default: `origin/main...HEAD`) and write `walkthrough.md` to disk. That skill installs from [prisma/ignite](https://github.com/prisma/ignite) and is not part of this repo; if it is not installed, derive the walkthrough from the diff yourself. The walkthrough provides raw material — narrative steps, behavior changes, evidence links — but its default section order is **not** the PR shape. You will restructure it. +1. Run the `drive-pr-walkthrough` skill for the current branch vs base (default: `origin/main...HEAD`) and write `walkthrough.md` to disk. That skill lives in [prisma/ignite](https://github.com/prisma/ignite), not in this repo. If it is not installed, either install it with `npx skills add prisma/ignite/skills/.pilot --skill '*'` (the command the root `CLAUDE.md` documents) or derive the walkthrough from the diff yourself. The walkthrough provides raw material — narrative steps, behavior changes, evidence links — but its default section order is **not** the PR shape. You will restructure it. 2. Write the PR body to disk as a working file (e.g. `wip/pr-<num>-body.md`) following the **Required structure** above. Reuse the walkthrough's narrative, behavior bullets, and evidence links where they fit; restructure to lead with the code sample and the decision, and to end with alternatives. 3. **Adjust links for GitHub**: - Keep helpful link text (file paths, optionally line ranges). diff --git a/skills-contrib/draft-release-notes/SKILL.md b/skills-contrib/draft-release-notes/SKILL.md index 268d76d5649b..6a19c02d07be 100644 --- a/skills-contrib/draft-release-notes/SKILL.md +++ b/skills-contrib/draft-release-notes/SKILL.md @@ -143,6 +143,7 @@ For a **skipped-publish range** (more than one minor in this release — see gra Prose tells a reader *that* something changed; a short before/after snippet shows them *what it looks like*, which is what they actually need to act. For the most code-visible breaking changes — contract-shape changes, authoring-surface changes, runtime-option or builder-API changes — nest a compact `before` / `after` example under the prose bullet. - **Source it from the recipe, don't invent it.** The matching `<transition-label>` upgrade recipe (authored via [`record-upgrade-instructions`](../record-upgrade-instructions/SKILL.md)) already contains authoritative before/after migration code — lift the snippet from there so it stays accurate. If the change is only visible in the emitted `contract.json` / `contract.d.ts`, a minimal shape diff from the recipe or the PR diff is fine. +- **When no recipe directory exists**, derive the example from the PR diff instead, or omit the example and describe the required action in prose. Never invent a migration the diff does not show. - **Keep it tight.** A few lines before, a few lines after — enough to show the shape, not the whole file. - **Lead with PSL.** When the change is on the authoring surface, write the example in PSL (```` ```prisma ````, never ```` ```psl ````), per the repo's authoring-surface convention. Use TS or JSON only when the change is genuinely a TS-surface change (a builder/runtime option, a consumer reading the emitted `.d.ts`) or an emitted-shape change with no PSL form. - **Skip operational-only breaks.** Version-floor bumps, peer-dependency changes, and package removals/extractions have no illuminating code diff — prose suffices for those. diff --git a/skills-contrib/github-review-iteration/SKILL.md b/skills-contrib/github-review-iteration/SKILL.md index 55c9c046fdb5..a101fef6b53c 100644 --- a/skills-contrib/github-review-iteration/SKILL.md +++ b/skills-contrib/github-review-iteration/SKILL.md @@ -27,6 +27,8 @@ All script paths in this document are **relative to this skill's directory**. Us **Run the scripts from the repository root**, addressing them by their full path under the skills installation. The reviews root defaults to `wip/reviews` resolved against the working directory, so a run started elsewhere writes artifacts outside the repo-root `wip/` tree that `.gitignore` covers. Pass `--reviews-root <repo-root>/wip/reviews` if you must run from another directory. +To run a path from the repository root, prefix it with this skill's installed location — under Claude Code, `.claude/skills/github-review-iteration/`. So `../review-fetch-phase/scripts/fetch-review-state.mjs` becomes `.claude/skills/review-fetch-phase/scripts/fetch-review-state.mjs`. + ## Usage This skill supports subcommands: @@ -67,7 +69,7 @@ Derived artifacts: When you need a thin wrapper for path setup + standard script calls, run: ```bash -node ./scripts/review-iterate.mjs --pr <PR_URL> +node .claude/skills/github-review-iteration/scripts/review-iterate.mjs --pr <PR_URL> ``` For phase-specific execution without full orchestration, use: diff --git a/skills-contrib/review-implement-phase/SKILL.md b/skills-contrib/review-implement-phase/SKILL.md index f65917ccf285..50e0e34777e8 100644 --- a/skills-contrib/review-implement-phase/SKILL.md +++ b/skills-contrib/review-implement-phase/SKILL.md @@ -63,11 +63,13 @@ If missing, instruct user to run: - issue comments via `addComment` (or wrapper script) - Before starting implementation: - **Detect pending reviews authored by the acting user** on this PR: - `gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$pr){reviews(last:20,states:PENDING){nodes{id author{login}}}}}}' -F owner=<owner> -F repo=<repo> -F pr=<number>` - - If any exist, **halt** and clean them up (submit or dismiss) before continuing. + `gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!){viewer{login} repository(owner:$owner,name:$repo){pullRequest(number:$pr){reviews(last:100,states:PENDING){pageInfo{hasPreviousPage startCursor} nodes{id author{login}}}}}}' -F owner=<owner> -F repo=<repo> -F pr=<number> --jq '.data as $d | $d.repository.pullRequest.reviews.nodes[] | select(.author.login == $d.viewer.login)'` + - The `author.login` filter matters: another user's pending review is not yours to submit or dismiss, and must not block this workflow. `--jq` is `gh`'s built-in filter and needs no `jq` binary. + - GitHub allows one pending review per user per PR, so the filtered result is either empty or a single node. `last:100` covers the page; if `hasPreviousPage` is true and nothing matched, page back with `before: <startCursor>` before concluding there is none. + - If one exists, **halt** and clean it up (submit or dismiss) before continuing. - After posting any "On it" / "Done" comment: - - **Re-check for pending reviews authored by the acting user**. - - If any exist, the workflow is **blocked** until they are cleaned up. + - **Re-check for a pending review authored by the acting user**, with the same filtered query. + - If one exists, the workflow is **blocked** until it is cleaned up. - Implementation requirement: - For `review_thread` targets, always reply using **thread replies** (never inline PR review comments). - If you only have the thread node id, first fetch the thread’s primary comment node id, then call `addPullRequestReviewThreadReply`. diff --git a/skills-contrib/write-architecture-docs/SKILL.md b/skills-contrib/write-architecture-docs/SKILL.md index 8f657cbe8cd8..683be9388f1b 100644 --- a/skills-contrib/write-architecture-docs/SKILL.md +++ b/skills-contrib/write-architecture-docs/SKILL.md @@ -44,7 +44,7 @@ Architecture docs in this repo serve two audiences: team members working on the Good: "Prisma Next supports multiple database families. SQL was the first; MongoDB is the second." Bad: "MongoDB is a database family in Prisma Next. The contract, ORM, execution pipeline, and plugin framework all generalize across fundamentally different data models — the same `ContractBase` domain structure, the same `Collection` chaining API, and the same plugin lifecycle work for both SQL and MongoDB." -**Inline summaries with ADR links.** When referencing an ADR, summarize the key idea in the text and link the ADR for depth. The doc should be understandable without following any links. +**Inline summaries with ADR links.** When referencing an ADR, summarize the key idea in the text and link the ADR for depth. The doc should be understandable without following any links. The example below shows the link as it must appear in the subsystem doc you are writing, so its path is relative to that doc's location under `docs/architecture docs/subsystems/`. Good: "An owned model declares `owner: \"User\"` — a domain fact about aggregate membership. Its data lives within the owner's storage. See [ADR 177](../adrs/ADR%20177%20-%20Ownership%20replaces%20relation%20strategy.md)." Bad: "See [ADR 177](...) for how embedding works." From f746c15017cd98b8f28ef951877a14a58eeeebdb Mon Sep 17 00:00:00 2001 From: Oleksii Orlenko <robot@aqrln.net> Date: Thu, 20 Aug 2026 16:05:41 +0200 Subject: [PATCH 3/4] docs(skills): resolve the walkthrough base and page the pending-review query (TML-3223) - create-pr: run drive-pr-walkthrough against the BASE_BRANCH resolved in Step 1, not a hardcoded origin/main. - review-implement-phase: keep pageInfo beside the filtered matches, and say to page back with before until the match is found or hasPreviousPage is false, in both the initial check and the re-check. Claude-Session: https://claude.ai/code/session_01NnNjsNcPMtbJZhnZz5Zzbe Signed-off-by: Oleksii Orlenko <robot@aqrln.net> --- skills-contrib/create-pr/SKILL.md | 2 +- skills-contrib/review-implement-phase/SKILL.md | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/skills-contrib/create-pr/SKILL.md b/skills-contrib/create-pr/SKILL.md index a99ec97f27c4..672335d6f2cf 100644 --- a/skills-contrib/create-pr/SKILL.md +++ b/skills-contrib/create-pr/SKILL.md @@ -127,7 +127,7 @@ Read `.github/PULL_REQUEST_TEMPLATE.md` once before drafting. The template's req #### Drafting workflow -1. Run the `drive-pr-walkthrough` skill for the current branch vs base (default: `origin/main...HEAD`) and write `walkthrough.md` to disk. That skill lives in [prisma/ignite](https://github.com/prisma/ignite), not in this repo. If it is not installed, either install it with `npx skills add prisma/ignite/skills/.pilot --skill '*'` (the command the root `CLAUDE.md` documents) or derive the walkthrough from the diff yourself. The walkthrough provides raw material — narrative steps, behavior changes, evidence links — but its default section order is **not** the PR shape. You will restructure it. +1. Run the `drive-pr-walkthrough` skill for the current branch vs base (`origin/$BASE_BRANCH...HEAD`, using the `BASE_BRANCH` resolved in Step 1; `origin/main...HEAD` when it resolves to the default) and write `walkthrough.md` to disk. That skill lives in [prisma/ignite](https://github.com/prisma/ignite), not in this repo. If it is not installed, either install it with `npx skills add prisma/ignite/skills/.pilot --skill '*'` (the command the root `CLAUDE.md` documents) or derive the walkthrough from the diff yourself. The walkthrough provides raw material — narrative steps, behavior changes, evidence links — but its default section order is **not** the PR shape. You will restructure it. 2. Write the PR body to disk as a working file (e.g. `wip/pr-<num>-body.md`) following the **Required structure** above. Reuse the walkthrough's narrative, behavior bullets, and evidence links where they fit; restructure to lead with the code sample and the decision, and to end with alternatives. 3. **Adjust links for GitHub**: - Keep helpful link text (file paths, optionally line ranges). diff --git a/skills-contrib/review-implement-phase/SKILL.md b/skills-contrib/review-implement-phase/SKILL.md index 50e0e34777e8..323439d52498 100644 --- a/skills-contrib/review-implement-phase/SKILL.md +++ b/skills-contrib/review-implement-phase/SKILL.md @@ -63,12 +63,13 @@ If missing, instruct user to run: - issue comments via `addComment` (or wrapper script) - Before starting implementation: - **Detect pending reviews authored by the acting user** on this PR: - `gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!){viewer{login} repository(owner:$owner,name:$repo){pullRequest(number:$pr){reviews(last:100,states:PENDING){pageInfo{hasPreviousPage startCursor} nodes{id author{login}}}}}}' -F owner=<owner> -F repo=<repo> -F pr=<number> --jq '.data as $d | $d.repository.pullRequest.reviews.nodes[] | select(.author.login == $d.viewer.login)'` + `gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!,$before:String){viewer{login} repository(owner:$owner,name:$repo){pullRequest(number:$pr){reviews(last:100,states:PENDING,before:$before){pageInfo{hasPreviousPage startCursor} nodes{id author{login}}}}}}' -F owner=<owner> -F repo=<repo> -F pr=<number> --jq '.data as $d | $d.repository.pullRequest.reviews | {mine: [.nodes[] | select(.author.login == $d.viewer.login)], pageInfo}'` - The `author.login` filter matters: another user's pending review is not yours to submit or dismiss, and must not block this workflow. `--jq` is `gh`'s built-in filter and needs no `jq` binary. - - GitHub allows one pending review per user per PR, so the filtered result is either empty or a single node. `last:100` covers the page; if `hasPreviousPage` is true and nothing matched, page back with `before: <startCursor>` before concluding there is none. + - The filter keeps `pageInfo` beside the matches, because an empty `mine` alone cannot tell "no pending review" from "the match is on an earlier page". Read both: while `mine` is empty and `pageInfo.hasPreviousPage` is true, re-run the query with `-f before=<pageInfo.startCursor>`. Conclude there is no pending review only when `mine` is empty and `hasPreviousPage` is false. + - GitHub allows one pending review per user per PR, so `mine` holds at most one node across all pages. - If one exists, **halt** and clean it up (submit or dismiss) before continuing. - After posting any "On it" / "Done" comment: - - **Re-check for a pending review authored by the acting user**, with the same filtered query. + - **Re-check for a pending review authored by the acting user**, with the same filtered query and the same paging rule: keep reading `pageInfo` until `mine` is non-empty or `hasPreviousPage` is false. - If one exists, the workflow is **blocked** until it is cleaned up. - Implementation requirement: - For `review_thread` targets, always reply using **thread replies** (never inline PR review comments). From 3d943a5ad382f0d4db899b19c21a4be4629efaab Mon Sep 17 00:00:00 2001 From: Oleksii Orlenko <robot@aqrln.net> Date: Thu, 20 Aug 2026 16:22:33 +0200 Subject: [PATCH 4/4] docs(skills): reuse Step 1's resolved base ref for the walkthrough (TML-3223) Step 1 resolves BASE_BRANCH as a local ref with a remote fallback and an explicit override. The walkthrough step names the same ref and the same fallback rather than always reaching for the remote-tracking branch. Claude-Session: https://claude.ai/code/session_01NnNjsNcPMtbJZhnZz5Zzbe Signed-off-by: Oleksii Orlenko <robot@aqrln.net> --- skills-contrib/create-pr/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills-contrib/create-pr/SKILL.md b/skills-contrib/create-pr/SKILL.md index 672335d6f2cf..8ed8edd510a4 100644 --- a/skills-contrib/create-pr/SKILL.md +++ b/skills-contrib/create-pr/SKILL.md @@ -127,7 +127,7 @@ Read `.github/PULL_REQUEST_TEMPLATE.md` once before drafting. The template's req #### Drafting workflow -1. Run the `drive-pr-walkthrough` skill for the current branch vs base (`origin/$BASE_BRANCH...HEAD`, using the `BASE_BRANCH` resolved in Step 1; `origin/main...HEAD` when it resolves to the default) and write `walkthrough.md` to disk. That skill lives in [prisma/ignite](https://github.com/prisma/ignite), not in this repo. If it is not installed, either install it with `npx skills add prisma/ignite/skills/.pilot --skill '*'` (the command the root `CLAUDE.md` documents) or derive the walkthrough from the diff yourself. The walkthrough provides raw material — narrative steps, behavior changes, evidence links — but its default section order is **not** the PR shape. You will restructure it. +1. Run the `drive-pr-walkthrough` skill for the current branch vs base — `"$BASE_BRANCH...HEAD"` with the `BASE_BRANCH` resolved in Step 1, falling back to `"origin/$BASE_BRANCH...HEAD"` exactly as Step 1's commands do (`main...HEAD` when `BASE_BRANCH` resolves to the default) — and write `walkthrough.md` to disk. That skill lives in [prisma/ignite](https://github.com/prisma/ignite), not in this repo. If it is not installed, either install it with `npx skills add prisma/ignite/skills/.pilot --skill '*'` (the command the root `CLAUDE.md` documents) or derive the walkthrough from the diff yourself. The walkthrough provides raw material — narrative steps, behavior changes, evidence links — but its default section order is **not** the PR shape. You will restructure it. 2. Write the PR body to disk as a working file (e.g. `wip/pr-<num>-body.md`) following the **Required structure** above. Reuse the walkthrough's narrative, behavior bullets, and evidence links where they fit; restructure to lead with the code sample and the decision, and to end with alternatives. 3. **Adjust links for GitHub**: - Keep helpful link text (file paths, optionally line ranges).