@salesforce/afv-skills 1.25.0 → 1.27.0

package/skills/dx-devops-test-pipeline-configure/references/error-handling.md

@@ -0,0 +1,39 @@
+# Error Handling — All Modes
+
+Never expose raw API error messages, stack traces, or JSON payloads to the user. Map response status codes to plain-language messages.
+
+## Mode A — Configure a test provider
+
+| Status | User-facing message |
+|---|---|
+| 400 | "The request was invalid. Check that the provider ID and pipeline ID are correct." |
+| 403 | "You don't have permission to configure test providers on this pipeline." |
+| 404 | "The pipeline or test provider was not found." |
+| 409 | "That provider appears to already be configured on this pipeline. To pick up new suites, re-sync it instead." |
+| 500 | "A server error occurred. Try again in a few minutes." |
+
+## Mode B — Sync a configured provider
+
+| Status | User-facing message |
+|---|---|
+| 400 | "The sync request was invalid. Check that the provider ID and pipeline ID are correct." |
+| 403 | "You don't have permission to sync test providers on this pipeline." |
+| 404 | "The pipeline or test provider was not found." |
+| 500 | "A server error occurred. Try again in a few minutes." |
+
+## Mode C — Configure a quality gate
+
+| Status | User-facing message |
+|---|---|
+| 400 | "The quality gate configuration is invalid. Check that all rule types and thresholds are correct." |
+| 403 | "You don't have permission to configure quality gates on this org." |
+| 500 | "A server error occurred. Try again in a few minutes." |
+
+## Prerequisite / environment errors
+
+| Error condition | Response |
+|---|---|
+| `sf org list` fails entirely | "Could not reach the Salesforce CLI. Make sure `sf` is installed and on your PATH." |
+| `sf org display` returns auth error | Surface plain-language re-auth instructions. Do not expose the raw error. |
+| `DevopsPipeline` query fails with 5xx | "The DevOps Center org is returning a server error. Try again in a few minutes." |
+| Any check throws unexpectedly | "Something went wrong checking prerequisites. Error: [plain summary]. Let's try again — or resolve it manually and let me know when ready." |

package/skills/dx-devops-test-pipeline-configure/references/gotchas.md

@@ -0,0 +1,37 @@
+# Critical Gotchas
+
+## Duplicate provider configuration (the big one)
+
+`POST /connect/devops/pipeline/<pipelineId>/testProvider` **creates a new provider configuration record** (`DevopsPipelineTestProvider`). Use it ONLY to configure a provider for the **first time** (Mode A).
+
+To re-sync an already-configured provider for new suites, use `POST /connect/devops/sync` (Mode B). Calling the configure endpoint on an already-configured provider produces **duplicate** `DevopsPipelineTestProvider` records.
+
+**Decision tree:**
+
+- Provider is **Available** → configure via `POST .../pipeline/<id>/testProvider` (Mode A).
+- Provider is **Configured**, new suites missing → sync via `POST /connect/devops/sync` (Mode B).
+- Provider is **Configured**, suites missing only when assigning to a stage → stage-assignment gap; redirect to `dx-devops-test-suite-assignments-configure`.
+
+## API name differences
+
+| Issue | Resolution |
+|---|---|
+| `DevopsPipeline` query returns empty | DevOps Center not installed on the target org, or wrong org alias — ask the user to verify |
+| `DevopsWorkItem` sObject not supported | Use `WorkItem` (no namespace) — the correct API name for this org version |
+| `sf plugins` doesn't match `agentforce` | The installed plugin is `@salesforce/plugin-agent` — match on `plugin-agent` too |
+
+## Trigger-type rules
+
+| Issue | Resolution |
+|---|---|
+| Review trigger is pipeline-level, not stage-level | Query `DevopsPipelineStageTrigger` where `TriggerType = 'Review'` and `RelatedRecordId = <pipelineId>` |
+| Connect API `testSuites` returns empty with `?stageId=` | Use `?triggerId=<reviewTriggerId>` — `stageId` only works for stage-level triggers |
+
+## Endpoint families
+
+- **Configure provider:** `POST /connect/devops/pipeline/<pipelineId>/testProvider`
+- **Sync provider:** `POST /connect/devops/sync`
+- **List providers:** `GET /connect/devopstesting/pipeline/<pipelineId>/testProviders?status=all`
+- **Quality gate:** `POST /connect/devopstesting/qualityGate`
+
+Note the `devops` vs `devopstesting` path segment differs between sync/configure and the listing/quality-gate endpoints — copy them exactly.

package/skills/dx-devops-test-pipeline-configure/references/prerequisite-checks.md

@@ -0,0 +1,112 @@
+# Prerequisite Checks — Shared DevOps Center Gate
+
+Shared environment gate for every DevOps Center testing skill. Run these checks **before** any query or system call. On any failure, surface the plain-language message and stop until the user resolves it — never proceed to a write with an unverified environment.
+
+> **API version:** All DevOps testing system calls target Salesforce API **v67.0** (minimum required).
+
+**Important:** All DevOps Center data (pipelines, stages, test suites, executions) lives in the Salesforce org — NOT in the local repository. Never search the filesystem for pipeline configuration. Always query the org using `sf data query` or `sf api request rest`.
+
+**Object model — use the STANDARD objects, never the `sf_devops__` managed package:** DevOps Center testing data lives in standard platform objects — `DevopsPipeline`, `DevopsPipelineStage`, `DevopsPipelineStageTrigger`, `DevopsTestSuite`, `DevopsTestSuiteStage`, `DevopsTestSuiteExecution`, `DevopsProject`, `WorkItem`. Do **NOT** query the legacy managed-package objects (`sf_devops__Pipeline__c`, `sf_devops__Pipeline_Stage__c`, etc.) and do **NOT** gate on a `PackageLicense` / namespace check for `sf_devops`. "DevOps Center installed" is determined **solely** by whether `DevopsPipeline` is queryable and returns records (Prerequisite 4) — never by the presence of the `sf_devops__` namespace. If a `sf_devops__*` object is missing, that is expected and is NOT evidence that DevOps Center is uninstalled.
+
+## How skills use this
+
+Run Prerequisites 1–4 in order. Prerequisite 5 (stage) is run **only** when the operation targets a specific pipeline stage (configuring a gate, running/retriggering a suite, mapping a suite). Carry forward the resolved `doce-org-alias`, `pipelineId`, and (when applicable) `stageId`.
+
+Resolve the **DevOps Center org alias** without asking the user unless genuinely ambiguous:
+1. If the user named an org alias in their message, use it.
+2. Otherwise, use the default org (`sf org display --json`, no `--target-org`).
+3. Only if the default org has no `DevopsPipeline` records (Prereq 4 fails), ask: "Which org alias is your DevOps Center org?"
+
+---
+
+## Prerequisite 1 — Salesforce org: active login
+
+```bash
+sf org list --json
+```
+
+Look for at least one entry in `result.nonScratchOrgs`, `result.scratchOrgs`, or `result.sandboxes` with `"connectedStatus": "Connected"`.
+
+- **Pass:** at least one org is Connected
+- **Fail:** no orgs listed, or all show a non-connected status
+
+**On fail:** "No authenticated Salesforce org found. Run `sf org login web --alias <your-alias>` in your terminal, then come back."
+
+---
+
+## Prerequisite 2 — Agentforce DX plugin installed
+
+```bash
+sf plugins --json
+```
+
+Look for a plugin entry whose `name` contains `plugin-agent`, `agentforce`, or `einstein` (case-insensitive).
+
+- **Pass:** plugin found
+- **Fail:** no matching entry
+
+**On fail:** "The Agentforce DX Plugin is not installed. Run `sf plugins install @salesforce/plugin-agent`, then restart the IDE and try again."
+
+---
+
+## Prerequisite 3 — DevOps Center org authenticated
+
+```bash
+sf org display --target-org <doce-org-alias> --json
+```
+
+Check that `"connectedStatus"` is `"Connected"`.
+
+- **Pass:** Connected
+- **Fail:** expired session or error
+
+**On fail:** "Your DevOps Center org session has expired. Run `sf org login web --alias <doce-org-alias>` to re-authenticate."
+
+---
+
+## Prerequisite 4 — Pipeline identified
+
+```bash
+sf data query \
+  --query "SELECT Id, Name, CreatedDate FROM DevopsPipeline ORDER BY Name ASC" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+- **Pass (exactly one):** use it automatically — do NOT ask.
+- **Pass (multiple):** if the user already named a pipeline, match by name. Otherwise display a numbered list and ask:
+  ```text
+  Found <N> pipelines:
+  1. <Name>
+  2. <Name>
+  Which pipeline would you like to work with?
+  ```
+- **Fail (no records):** "No DevOps Center pipeline found. Create a project and pipeline in DevOps Center before using the DevOps Testing Skills."
+- **Fail (unsupported object):** "DevOps Center does not appear to be installed on `<doce-org-alias>`. Check that you're pointing at the correct org."
+
+---
+
+## Prerequisite 5 — Pipeline stage identified (conditional)
+
+Run **only** when the operation targets a specific stage (e.g. configuring a quality gate).
+
+If the user's message already names a stage (e.g. "Integration", "Staging", "Production"), use that name directly — do NOT ask again. Look up its Id:
+
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' AND Name = '<stageName>'" \
+  --target-org <doce-org-alias> --json
+```
+
+Only if no stage is mentioned, fetch the full list and ask which one:
+
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' ORDER BY Name ASC" \
+  --target-org <doce-org-alias> --json
+```
+
+Then ask: "Which pipeline stage are we working with?" — do NOT ask for an org alias; stages are resolved by name from the pipeline.
+
+- **Pass:** stage Id and Name confirmed
+- **Deferred:** not required until the operation needs it

package/skills/dx-devops-test-pipeline-configure/references/syncing-test-providers.md

@@ -0,0 +1,69 @@
+# Mode B — Sync a Configured Provider
+
+Re-syncs an already-*Configured* test provider on a DevOps Center pipeline so that suites added to the provider since it was last configured become available for assignment to stages.
+
+**Confirmation required:** Yes — explicit confirmation before the sync is triggered.
+
+## Inputs
+
+| Variable | Source |
+|---|---|
+| `doce-org-alias` | Prerequisite 1 |
+| `pipelineId` | Prerequisite 4 (pipeline selection) |
+| `testProviderId` | Resolved by fetching the pipeline's test providers (Step 1 below) |
+
+Prerequisite 5 (stage) is **not** required — providers are synced at the pipeline level.
+
+---
+
+## Step 1 — Fetch test providers to resolve the provider ID
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/testProviders?status=all" \
+  --target-org <doce-org-alias>
+```
+
+Each provider entry includes `testProviderId`, `testProviderName`, and a status (Configured vs. Available). Present a short summary grouped by status (same format as Mode A).
+
+- **Only a Configured provider can be synced.** If the user names an *Available* (not-yet-configured) provider, explain it must be configured first — use **Mode A** (`references/configuring-test-provider.md`).
+- If the pipeline has no configured providers, report that and stop — do NOT fabricate a provider or ID.
+
+## Step 2 — Confirmation gate
+
+**Required — do not call the API before the user confirms.**
+
+> "I'll re-sync `<testProviderName>` on the `<pipelineName>` pipeline to pick up any new suites. Confirm?"
+
+Do not proceed until the user gives an affirmative response.
+
+## Step 3 — Trigger the sync
+
+On confirmation, call the sync endpoint with the provider ID(s) and pipeline ID:
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devops/sync" \
+  --method POST \
+  --body '{
+    "testProviderIds": ["<testProviderId>"],
+    "pipelineId": "<pipelineId>"
+  }' \
+  --target-org <doce-org-alias>
+```
+
+`testProviderIds` is a list — multiple configured providers can be synced in one call.
+
+## On success
+
+> "Provider `<testProviderName>` sync started. The operation is running asynchronously — new suites will be available shortly."
+
+The sync runs asynchronously; newly synced suites can then be assigned to stages with `dx-devops-test-suite-assignments-configure`.
+
+---
+
+## Critical gotcha
+
+**Do NOT use** `POST /connect/devops/pipeline/<pipelineId>/testProvider` to sync — that endpoint **creates a new provider configuration** and will result in duplicate `DevopsPipelineTestProvider` records. Sync only via `POST /connect/devops/sync`. See `references/gotchas.md`.
+
+See `references/error-handling.md` for status-code responses.

package/skills/dx-devops-test-suite-assignments-configure/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: dx-devops-test-suite-assignments-configure
+description: "Recommends and manages DevOps Center test suite assignments for pipeline stages. Mode A analyzes a commit diff against assigned suite metadata to recommend relevant existing suites and flag coverage gaps (pure reasoning). Modes B-D assign a single suite, bulk-map multiple suites with a mandatory impact preview, or add/remove test classes with governance rules, via the testSuiteStages Connect API. Use this skill to recommend suites for a commit, assign or map suites to stages, or add/remove tests in a suite. TRIGGER when: the user asks which suites to run for a commit/diff or what covers their changes; a suite is unlinked and the user wants it assigned; the user wants to configure suite-to-stage mappings, assign multiple suites, or add/remove/sync tests in a suite. DO NOT TRIGGER when: configuring or syncing a test provider (use dx-devops-test-pipeline-configure), running suites (use dx-devops-test-suite-run), or authoring/running tests directly (use platform-apex-test-generate or platform-apex-test-run)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Configure DevOps Center Suite Assignments
+
+Recommends which existing test suites to run for a change, and manages how suites are assigned and mapped to pipeline stages. These operations share the same suite-stage metadata: a recommendation surfaces relevant suites and flags gaps, and those gaps lead directly into assignment.
+
+> **API version:** All DevOps testing system calls target Salesforce API **v67.0** (minimum required).
+
+**Important:** All DevOps Center data lives in the Salesforce org — NOT the local repo. Never search the filesystem for suite configuration. Always query the org with `sf data query` or `sf api request rest`.
+
+---
+
+## Step 1 — Run prerequisites first (always)
+
+Run the prerequisite checks in `references/prerequisite-checks.md` before any query or system call. On any failure, surface the plain-language message and stop.
+
+- **Mode A (recommend):** Prerequisites 1–4 (org login, plugin, DevOps Center org auth, pipeline identified). No stage required — recommendation reads the pipeline-level Review trigger.
+- **Modes B–D (assign/map/classes):** Prerequisites 1–4 **and** Prerequisite 5 (stage). You need `doce-org-alias`, `pipelineId`, and `stageId`.
+
+---
+
+## Step 2 — Select the mode
+
+| If the user wants to… | Mode | Follow |
+|---|---|---|
+| Know **which suites to run** for a commit/diff, or what covers their changes | **A — Recommend suites** | `references/recommendation-logic.md` |
+| Assign **one** suite to a stage as a one-off | **B — Assign a single suite** | `references/suite-assignment-modes.md` |
+| **Bulk-map** multiple suites to a stage as a testing strategy | **C — Map multiple suites** | `references/suite-assignment-modes.md` |
+| **Add/remove** individual test classes within a suite assignment | **D — Add/remove classes** | `references/suite-assignment-modes.md` |
+
+Mode A is pure reasoning (no writes). Modes B–D mutate org state via the same `testSuiteStages` endpoint (`references/api-endpoint.md`).
+
+**How A feeds B–D:** When recommendation flags a relevant suite that is *not assigned* to the stage, that gap is the input to Mode B/C. When it flags a *new method with no suite coverage*, direct the developer to author tests manually (v1 constraint — never suggest generating tests here).
+
+---
+
+## Step 3 — Governance & confirmation (Modes B–D)
+
+Modes B–D **must** confirm before any write:
+
+- **Mode B** — single confirmation prompt naming the suite, stage, and event.
+- **Mode C** — a **mandatory impact-preview table** (Suite / Stage / Event / Action) before the confirmation gate.
+- **Mode D** — re-present the final test list before confirming. **Rejected tests must be EXCLUDED from the payload.** If tests were modified during review, re-present the final list before requesting confirmation. Never call without explicit approval.
+
+Do not call the API until the user gives an affirmative response. If the user declines, stop without writing. Full wording for each gate is in `references/suite-assignment-modes.md`.
+
+Mode A (recommendation) makes no writes and needs no confirmation gate.
+
+---
+
+## Step 4 — Execute and report
+
+Follow the chosen reference file:
+
+- `references/recommendation-logic.md` — Mode A: diff classification, provider matching, ranking, gap flagging, output format.
+- `references/suite-assignment-modes.md` — Modes B–D: inputs, confirmation wording, success messages.
+- `references/api-endpoint.md` — the shared `testSuiteStages` POST payload schema (Modes B–D).
+- `references/error-handling.md` — status-code → plain-language tables.
+
+Never expose raw API errors, stack traces, or JSON to the user.
+
+---
+
+## Related skills
+
+- **`dx-devops-test-pipeline-configure`** — if the suite you want to assign doesn't appear yet, configure or re-sync the provider; also configures quality gates on a stage after mapping.
+- **`dx-devops-test-suite-run`** — execute a recommended/assigned suite on a stage.
+- **`dx-devops-test-failures-analyze`** — analyze failures and improvement suggestions for the tests within a suite.

package/skills/dx-devops-test-suite-assignments-configure/references/api-endpoint.md

@@ -0,0 +1,30 @@
+# API Endpoint — testSuiteStages (Modes B–D)
+
+All three assignment modes (B, C, D) use the same Connect API endpoint. Substitute all `<placeholder>` values before executing.
+
+```bash
+sf api request rest "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/testSuiteStages" --method POST --body '{"pipelineStageId":"<stageId>","event":"<event>","assignments":[{"testSuiteId":"<id>","action":"add|remove"}]}' --target-org <doce-org-alias>
+```
+
+## Full payload schema
+
+```json
+{
+  "pipelineStageId": "<stageId>",
+  "event": "<event>",
+  "assignments": [
+    {"testSuiteId": "<suiteId1>", "action": "add"},
+    {"testSuiteId": "<suiteId2>", "action": "remove"}
+  ]
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `pipelineStageId` | string | The pipeline stage ID (from Prerequisite 5) |
+| `event` | string | `Pre-Promote`, `Post-Promote`, or `Review` |
+| `assignments` | array | One or more `{testSuiteId, action}` entries — `action` is `add` or `remove` |
+
+- **Mode B** sends a single `add` assignment.
+- **Mode C** sends multiple `add`/`remove` entries in one call (bulk mapping).
+- **Mode D** sends `add`/`remove` entries for the classes/suites being synced — rejected tests excluded.

package/skills/dx-devops-test-suite-assignments-configure/references/error-handling.md

@@ -0,0 +1,14 @@
+# Error Handling — Suite Assignments (Modes B–D)
+
+Never expose raw API error messages, stack traces, or JSON payloads to the user. Map response status codes to plain-language messages.
+
+| Status | User-facing message |
+|---|---|
+| 400 | "The request was invalid. Check that all suite and stage IDs are correct and the event type is valid." |
+| 403 | "You don't have permission to modify suite assignments on this pipeline." |
+| 404 | "The pipeline or stage was not found." |
+| 500 | "A server error occurred. Try again in a few minutes." |
+
+## Mode A (recommendation) errors
+
+Mode A makes only read queries. If a `sf data query` fails, report the problem in plain language and stop — do NOT fabricate suite names, recommendations, or coverage data. If no suites are assigned to the Review trigger, state that explicitly ("No test suites are currently assigned to the Review trigger for this pipeline").

package/skills/dx-devops-test-suite-assignments-configure/references/prerequisite-checks.md

@@ -0,0 +1,112 @@
+# Prerequisite Checks — Shared DevOps Center Gate
+
+Shared environment gate for every DevOps Center testing skill. Run these checks **before** any query or system call. On any failure, surface the plain-language message and stop until the user resolves it — never proceed to a write with an unverified environment.
+
+> **API version:** All DevOps testing system calls target Salesforce API **v67.0** (minimum required).
+
+**Important:** All DevOps Center data (pipelines, stages, test suites, executions) lives in the Salesforce org — NOT in the local repository. Never search the filesystem for pipeline configuration. Always query the org using `sf data query` or `sf api request rest`.
+
+**Object model — use the STANDARD objects, never the `sf_devops__` managed package:** DevOps Center testing data lives in standard platform objects — `DevopsPipeline`, `DevopsPipelineStage`, `DevopsPipelineStageTrigger`, `DevopsTestSuite`, `DevopsTestSuiteStage`, `DevopsTestSuiteExecution`, `DevopsProject`, `WorkItem`. Do **NOT** query the legacy managed-package objects (`sf_devops__Pipeline__c`, `sf_devops__Pipeline_Stage__c`, etc.) and do **NOT** gate on a `PackageLicense` / namespace check for `sf_devops`. "DevOps Center installed" is determined **solely** by whether `DevopsPipeline` is queryable and returns records (Prerequisite 4) — never by the presence of the `sf_devops__` namespace. If a `sf_devops__*` object is missing, that is expected and is NOT evidence that DevOps Center is uninstalled.
+
+## How skills use this
+
+Run Prerequisites 1–4 in order. Prerequisite 5 (stage) is run **only** when the operation targets a specific pipeline stage (configuring a gate, running/retriggering a suite, mapping a suite). Carry forward the resolved `doce-org-alias`, `pipelineId`, and (when applicable) `stageId`.
+
+Resolve the **DevOps Center org alias** without asking the user unless genuinely ambiguous:
+1. If the user named an org alias in their message, use it.
+2. Otherwise, use the default org (`sf org display --json`, no `--target-org`).
+3. Only if the default org has no `DevopsPipeline` records (Prereq 4 fails), ask: "Which org alias is your DevOps Center org?"
+
+---
+
+## Prerequisite 1 — Salesforce org: active login
+
+```bash
+sf org list --json
+```
+
+Look for at least one entry in `result.nonScratchOrgs`, `result.scratchOrgs`, or `result.sandboxes` with `"connectedStatus": "Connected"`.
+
+- **Pass:** at least one org is Connected
+- **Fail:** no orgs listed, or all show a non-connected status
+
+**On fail:** "No authenticated Salesforce org found. Run `sf org login web --alias <your-alias>` in your terminal, then come back."
+
+---
+
+## Prerequisite 2 — Agentforce DX plugin installed
+
+```bash
+sf plugins --json
+```
+
+Look for a plugin entry whose `name` contains `plugin-agent`, `agentforce`, or `einstein` (case-insensitive).
+
+- **Pass:** plugin found
+- **Fail:** no matching entry
+
+**On fail:** "The Agentforce DX Plugin is not installed. Run `sf plugins install @salesforce/plugin-agent`, then restart the IDE and try again."
+
+---
+
+## Prerequisite 3 — DevOps Center org authenticated
+
+```bash
+sf org display --target-org <doce-org-alias> --json
+```
+
+Check that `"connectedStatus"` is `"Connected"`.
+
+- **Pass:** Connected
+- **Fail:** expired session or error
+
+**On fail:** "Your DevOps Center org session has expired. Run `sf org login web --alias <doce-org-alias>` to re-authenticate."
+
+---
+
+## Prerequisite 4 — Pipeline identified
+
+```bash
+sf data query \
+  --query "SELECT Id, Name, CreatedDate FROM DevopsPipeline ORDER BY Name ASC" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+- **Pass (exactly one):** use it automatically — do NOT ask.
+- **Pass (multiple):** if the user already named a pipeline, match by name. Otherwise display a numbered list and ask:
+  ```text
+  Found <N> pipelines:
+  1. <Name>
+  2. <Name>
+  Which pipeline would you like to work with?
+  ```
+- **Fail (no records):** "No DevOps Center pipeline found. Create a project and pipeline in DevOps Center before using the DevOps Testing Skills."
+- **Fail (unsupported object):** "DevOps Center does not appear to be installed on `<doce-org-alias>`. Check that you're pointing at the correct org."
+
+---
+
+## Prerequisite 5 — Pipeline stage identified (conditional)
+
+Run **only** when the operation targets a specific stage (e.g. configuring a quality gate).
+
+If the user's message already names a stage (e.g. "Integration", "Staging", "Production"), use that name directly — do NOT ask again. Look up its Id:
+
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' AND Name = '<stageName>'" \
+  --target-org <doce-org-alias> --json
+```
+
+Only if no stage is mentioned, fetch the full list and ask which one:
+
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' ORDER BY Name ASC" \
+  --target-org <doce-org-alias> --json
+```
+
+Then ask: "Which pipeline stage are we working with?" — do NOT ask for an org alias; stages are resolved by name from the pipeline.
+
+- **Pass:** stage Id and Name confirmed
+- **Deferred:** not required until the operation needs it

package/skills/{recommending-devops-tests/SKILL.md → dx-devops-test-suite-assignments-configure/references/recommendation-logic.md}

@@ -1,28 +1,18 @@
----
-name: recommending-devops-tests
-description: "Analyzes a commit diff and available DevOps Center test suite metadata to recommend the most relevant existing test suites, then flags coverage gaps where no suite covers a new method — via pure reasoning, no system calls beyond the prerequisite queries. Use this skill when a developer wants to know which test suites to run for a specific commit or diff, what tests cover their changes, or wants suite recommendations at commit time. TRIGGER when: the user asks which test suites to run for a commit/diff, asks what tests cover their changes, or asks for suite recommendations before promoting. DO NOT TRIGGER when: authoring new tests (use platform-apex-test-generate) or running sf apex run test directly (use platform-apex-test-run)."
-metadata:
-  version: "1.0"
-  minApiVersion: "67.0"
----
-
-# Recommending DevOps Tests
+# Mode A — Recommend Suites for a Commit/Diff
 
-**Type:** Pure reasoning — no system calls beyond the prerequisite data-fetch queries documented below.
+**Type:** Pure reasoning — no system calls beyond the prerequisite data-fetch queries documented below. No writes.
 
 **What it does:** Analyzes the commit diff and available suite metadata to recommend the most relevant existing test suites assigned to the Review pipeline stage. Flags coverage gaps where no suite covers a new method.
 
----
-
 ## Prerequisites
 
-Load and follow the `checking-devops-prerequisites` skill first (Prerequisites 1–4). This skill needs a confirmed DevOps Center org alias and pipeline Id before it can proceed.
+Run Prerequisites 1–4 (`references/prerequisite-checks.md`). A confirmed DevOps Center org alias and `pipelineId` are required before proceeding. No stage prompt — recommendation reads the pipeline-level Review trigger.
 
 ---
 
 ## Step 1 — Fetch suite metadata
 
-Before reasoning can begin, fetch the test suite metadata assigned to the Review pipeline stage. This requires two queries.
+Two queries are required before reasoning.
 
 **1a — Find the Review pipeline stage trigger:**
 
@@ -48,9 +38,7 @@ Each row provides: `TestSuiteId`, `TestSuite.Name`, `IsQualityGateEnabled`, and
 
 > Note: Do NOT use the beta `/connect/devops/.../testSuites` endpoint — it returns empty results. Query `DevopsTestSuiteStage` directly as shown above.
 
-Never expose raw API errors or raw JSON to the user. If a query fails, report the problem in plain language and stop.
-
-The commit diff comes from the user or surrounding context.
+Never expose raw API errors or raw JSON to the user. If a query fails, report the problem in plain language and stop. The commit diff comes from the user or surrounding context.
 
 ---
 
@@ -58,8 +46,6 @@ The commit diff comes from the user or surrounding context.
 
 ### 1 — Classify the diff by change type
 
-Parse the diff file extensions and paths to determine what types of changes were made:
-
 | File pattern | Change type |
 |---|---|
 | `*.cls`, `*.trigger` | Apex |
@@ -71,7 +57,7 @@ A single commit may contain multiple change types. Identify all of them.
 
 ### 2 — Map change types to test providers
 
-For each change type identified, match against the `testProviderName` of the fetched suites:
+For each change type, match against the `testProviderName` of the fetched suites:
 
 | Change type | Match suites whose `testProviderName` contains |
 |---|---|
@@ -81,7 +67,7 @@ For each change type identified, match against the `testProviderName` of the fet
 | LWC / JavaScript | `LWC` or `JavaScript` |
 | Code Analyzer (any) | `Code Analyzer` — then sub-filter by suite name convention: `recommended` → Apex/general rules (suggest for Apex and Java changes), `html` → suggest for HTML/LWC template changes, `css` → suggest for CSS changes. If no suite name matches the convention, suggest all Code Analyzer suites and note the ambiguity. |
 
-Only recommend suites whose provider matches at least one change type in the diff. Suites from non-matching providers are excluded from the recommendation.
+Only recommend suites whose provider matches at least one change type in the diff. Suites from non-matching providers are excluded.
 
 ### 3 — Rank matched suites
 
@@ -129,9 +115,7 @@ Coverage gaps (new methods — manual authoring required):
 
 Only recommend existing suites. Never suggest generating new tests. If gaps exist, direct the developer to author tests manually and explain exactly which methods need coverage.
 
----
-
-## Related skills
+## How recommendations feed assignment
 
-- To analyze failures from a run, use `analyzing-test-failures`.
-- To actually execute a recommended suite, use `running-devops-test-suite`.
+- A relevant suite that exists but is **not assigned** to the stage → use **Mode B/C** (`references/suite-assignment-modes.md`) to assign it.
+- To actually execute a recommended suite, use **`dx-devops-test-suite-run`**.