Reference pre-ci:affected and lean the pre-submit skill on the gate manifest

Author: dmerand

.agents/skills/_shared/shopify-cli-ci-repo-contracts.md

@@ -27,7 +27,7 @@ For normal PR CI work, start with `.github/workflows/tests-pr.yml`.
 
 ## Local pre-submit tooling
 
-- `pnpm pre-ci` runs the local subset of PR gates at full CI parity (type-check, lint, build, knip, codegen freshness, unit tests). It is heavier than routine work needs; prefer the minimal diff-derived set below, and reach for `pre-ci` when the user wants full confidence before a high-risk push.
+- `pnpm pre-ci` runs the local subset of PR gates at full CI parity (type-check, lint, build, knip, codegen freshness, unit tests). `pnpm pre-ci:affected` runs the diff-scoped fast variant (nx/vitest affected; skips the codegen freshness checks unless the diff touches commands, flags, or GraphQL). Default to affected; reach for full `pre-ci` before a high-risk push.
 - Codegen freshness is single-sourced in `package.json`: `pnpm codegen` regenerates all generated files; `pnpm codegen:check:graphql` / `:oclif` regenerate and assert a clean tree. The workflow's `graphql-schema` and `oclif-checks` jobs call these scripts, so local and CI cannot drift.
 - `bin/ci-gates.js` is the source of truth mapping each `tests-pr.yml` job to a `pre-ci` command or a `ci-only` reason. `pnpm check-ci-gates` (CI job `CI gate manifest`) fails if a workflow job is unclassified or if the Node/pnpm versions in `dev.yml` and `tests-pr.yml` disagree.
 

.agents/skills/cli-pre-submit-ci/SKILL.md

@@ -35,14 +35,16 @@ If the diff clearly maps to a narrow family, keep the investigation narrow.
 |---|---|
 | docs/config/wiring only, with no obvious workflow-enforced generator family | **stop there unless contradicted**: run lightweight sanity checks only (`git diff --check`, validate changed symlink targets, validate local markdown links if relevant); do not full-read large workflow/script files |
 | user is at PR time (`submit`, `open`, `update`, `restack`) | advisory mode: suggest minimal checks, staging needs, and likely CI risk; ask before running anything substantial |
-| user asks what to run before push | recommend the minimal high-signal checks implied by the workflow; mention `pnpm pre-ci` as the full-parity option for a high-risk push |
+| user asks what to run before push | `pnpm pre-ci:affected` for a diff-scoped fast check, or the minimal high-signal checks implied by the workflow; `pnpm pre-ci` for full parity before a high-risk push |
 | user asks what to commit or stage | reproduce the relevant generator/check path, then inspect git status and diffs |
 | user explicitly asks to run checks | run the minimal derived set, not the whole world |
 
 ### 2) Resolve the contract for the relevant family
 Only do this if the diff class suggests a real CI-family mapping, or if the user asks for broader confidence.
 
-Read sources in this order:
+The gate list is already resolved in [`bin/ci-gates.js`](../../../bin/ci-gates.js) — each `tests-pr.yml` job mapped to its local command (full and affected) or a ci-only reason. Read it first; `pnpm pre-ci` / `pnpm pre-ci:affected` run those gates, so most pre-submit work needs no per-diff YAML archaeology.
+
+When the manifest is not enough, resolve from the contract files in this order:
 
 1. relevant `.github/workflows/*.yml`
 2. `dev.yml`
@@ -75,7 +77,7 @@ After any generator, freshness check, or lightweight sanity pass:
 
 ## Gotchas
 
-- At PR time, do **not** automatically run the full workflow-equivalent validation set unless the user asks. `pnpm pre-ci` is that full set — offer it for high-risk pushes, but default to the minimal derived checks.
+- At PR time, do **not** automatically run the full workflow-equivalent validation set unless the user asks. `pnpm pre-ci` is that full set; `pnpm pre-ci:affected` is the diff-scoped fast check (and skips the codegen freshness checks unless the diff touches commands, flags, or GraphQL). Default to affected or the minimal derived checks.
 - `dev.yml` is a useful local entrypoint, but workflow YAML is the source of truth for what CI enforces.
 - Broad generated diffs are not automatically wrong; distinguish required churn from suspicious churn.
 - Do not stop at “run this command.” Explain what likely needs staging.

AGENTS.md

@@ -7,7 +7,7 @@ Entry point for contributors and coding agents. Canonical docs live under [`docs
 
 ## Before you push
 
-- Derive the minimal checks for your diff with the [`cli-pre-submit-ci`](./.agents/skills/cli-pre-submit-ci/SKILL.md) skill. For full local CI parity (slower), run `pnpm pre-ci`.
+- Run `pnpm pre-ci:affected` for a fast, diff-scoped pre-push check, or `pnpm pre-ci` for full CI parity before a high-risk push. The [`cli-pre-submit-ci`](./.agents/skills/cli-pre-submit-ci/SKILL.md) skill covers deriving the minimal set and what to stage.
 - After changing commands, flags, or GraphQL queries, run `pnpm codegen` and commit the regenerated files.
 - `pnpm check-ci-gates` keeps the local gate list ([`bin/ci-gates.js`](./bin/ci-gates.js)) and pinned tool versions in sync with the workflow.
 

docs/cli/get-started.md

@@ -72,7 +72,8 @@ Besides the scripts for building and running the CLIs, there are others that mig
 - `pnpm lint:fix`: Runs ESLint and Prettier checks for all the packages and fixes the fixable issues.
 - `pnpm type-check`: Type-checks all the packagesusing the Typescript `tsc` tool.
 - `pnpm clean`: Removes the `dist` directory from all the packages.
-- `pnpm pre-ci`: Runs the local subset of PR CI gates (type-check, lint, build, knip, codegen freshness, unit tests) at full parity with CI. Slower, for a high-risk push; for routine PRs derive the minimal checks for your diff (see the `cli-pre-submit-ci` agent skill).
+- `pnpm pre-ci`: Runs the local subset of PR CI gates (type-check, lint, build, knip, codegen freshness, unit tests) at full parity with CI. Slower, for a high-risk push.
+- `pnpm pre-ci:affected`: The diff-scoped fast variant for routine PRs (nx/vitest affected; skips codegen freshness checks unless the diff touches commands, flags, or GraphQL).
 - `pnpm codegen`: Regenerates all generated files (GraphQL types, OCLIF manifests, README, docs). Run after changing commands, flags, or queries, and commit the result.
 - `pnpm check-ci-gates`: Verifies the local CI-gate manifest stays in sync with the GitHub Actions workflow.