Invert shopify skill to validate-first, search-on-failure

[craigmichaelmartin]

What

Inverts the shopify master skill's core methodology from search-first, validate-last to validate-first, search-only-on-failure.

Stacked on top of #8142 (which introduces .agents/skills/shopify/SKILL.md), so this PR's diff is only the methodology change. Base: feature/shopify-validate-command.

Why

The old skill mandated a doc search before every task. But if the agent can produce an artifact that passes shopify validate, its recall was already current — the up-front search was wasted work. The reliable signal that training data is stale is a failing validator. So:

• Validation is the mandatory ground-truth gate on every producible artifact.
• Doc search becomes the remediation triggered only by a validation failure: search → correct against the docs → re-validate → loop until clean.

The new flow

1. Do the work from your own knowledge — build the query/mutation/component/config/scaffold directly; don't search yet.
2. Validate — mandatory, always — shopify validate [topic]. Outcome A (a chat example) → temp-file-validate; Outcome B (files changed) → validate every touched surface. Pass ⇒ done.
3. On validation failure → search, fix, re-validate — the failure means recall is stale for that surface; now shopify doc search/doc fetch, correct, and loop.

Edge case

Outcomes with no shopify validate surface (merchant-onboarding guidance, App Store review's read-only analysis, UCP flows, a bare docs question) have no validator to catch stale recall, so they are grounded with an up-front search — scoped explicitly as "the narrow exception the missing safety net demands, not a general rule."

Preserved

CLI command-discovery pattern, the family table (re-captioned to map family → validate topic → on-failure doc-search scope), the full 14-name --api-name valid set, the Outcome A/B validation rules, and the store-safety / read-only gotchas.

How it was produced

Three independent candidate rewrites (minimal-diff, loop-centered, validation-as-contract framings) were drafted and put through two adversarial reviewers each — checking for residual search-first language, faithful inversion, and coherent handling of the no-validator case. The minimal-diff candidate scored highest (no residual mandates, nothing lost, on-length); the intro was then softened to reconcile "mandatory" with the no-validator exception. Verified: grep finds no "search first / before producing any answer / both brackets" language remaining.

🤖 Generated with Claude Code

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/public/node/metadata.d.ts

@@ -34,7 +34,7 @@ export type SensitiveSchema<T> = T extends RuntimeMetadataManager<infer _TPublic
  * @returns A container for the metadata.
  */
 export declare function createRuntimeMetadataContainer<TPublic extends AnyJson, TSensitive extends AnyJson = Record<string, never>>(defaultPublicMetadata?: Partial<TPublic>): RuntimeMetadataManager<TPublic, TSensitive>;
-type CmdFieldsFromMonorail = PickByPrefix<MonorailEventPublic, 'cmd_all_'> & PickByPrefix<MonorailEventPublic, 'cmd_app_'> & PickByPrefix<MonorailEventPublic, 'cmd_create_app_'> & PickByPrefix<MonorailEventPublic, 'cmd_theme_'> & PickByPrefix<MonorailEventPublic, 'store_'> & PickByPrefix<MonorailEventPublic, 'env_auto_upgrade_'>;
+type CmdFieldsFromMonorail = PickByPrefix<MonorailEventPublic, 'cmd_all_'> & PickByPrefix<MonorailEventPublic, 'cmd_app_'> & PickByPrefix<MonorailEventPublic, 'cmd_create_app_'> & PickByPrefix<MonorailEventPublic, 'cmd_theme_'> & PickByPrefix<MonorailEventPublic, 'cmd_validate_'> & PickByPrefix<MonorailEventPublic, 'store_'> & PickByPrefix<MonorailEventPublic, 'env_auto_upgrade_'>;
 declare const coreData: RuntimeMetadataManager<CmdFieldsFromMonorail, {
     commandStartOptions: {
         startTime: number;

packages/cli-kit/dist/public/node/monorail.d.ts

@@ -77,6 +77,11 @@ export interface Schemas {
             cmd_app_validate_valid?: Optional<boolean>;
             cmd_app_validate_issue_count?: Optional<number>;
             cmd_app_validate_file_count?: Optional<number>;
+            cmd_validate_subcommand?: Optional<string>;
+            cmd_validate_result?: Optional<string>;
+            cmd_validate_api?: Optional<string>;
+            cmd_validate_api_version?: Optional<string>;
+            cmd_validate_json?: Optional<boolean>;
             cmd_dev_tunnel_type?: Optional<string>;
             cmd_dev_tunnel_custom_hash?: Optional<string>;
             cmd_dev_urls_updated?: Optional<boolean>;