@salesforce/afv-skills 1.17.0 → 1.19.0

package/skills/managing-cdc-enablement/references/deploy-troubleshooting.md

@@ -0,0 +1,73 @@
+# CDC Deploy Troubleshooting
+
+Errors observed during real org dry-runs while authoring this skill, with the metadata-side fix.
+
+## "Unable to find the specified channel"
+
+The `<eventChannel>` value doesn't match a channel known to the org.
+
+- For the default channel, the value must be exactly `ChangeEvents`. NOT `data/ChangeEvents`, NOT `/data/ChangeEvents`, NOT `data/ChangeEvent`.
+- For a custom channel, the value must match the channel's DeveloperName **including the `__chn` suffix** — e.g. `PartnerSync__chn`.
+- If the custom channel is in the same deploy, ensure it's in the same package directory so MDAPI orders the deploy correctly.
+
+## "...invalid event in the 'selectedEntity' field"
+
+`<selectedEntity>` must be the ChangeEvent entity, not the source object.
+
+| Source | Wrong | Right |
+|---|---|---|
+| `Account` | `Account` | `AccountChangeEvent` |
+| `Lead` | `Lead` | `LeadChangeEvent` |
+| `Order__c` | `Order__c` | `Order__ChangeEvent` |
+| `Custom__c` | `Custom__c` | `Custom__ChangeEvent` |
+
+For custom objects, swap the trailing `__c` for `__ChangeEvent` — the double underscore separator is preserved.
+
+## "Cannot create a new component with the namespace: <Object>"
+
+The member's fullName has two underscores between the entity and `ChangeEvent`. Salesforce parses `Foo__Bar` as `<namespace>__<name>` and rejects creation outside the org's own namespace.
+
+- Member fullName format: `<Entity>_ChangeEvent` (single underscore).
+- File name: `<Entity>_ChangeEvent.platformEventChannelMember-meta.xml`.
+
+This applies even when the source object has `__c` — the member fullName drops the `__c` and uses single underscore: file `Order_ChangeEvent.platformEventChannelMember-meta.xml`, fullName `Order_ChangeEvent`.
+
+## "The selected field, X.Y, isn't valid" (enrichedFields)
+
+Enrichment fields must be **single-hop API names on the source entity**. Field type doesn't matter — standard lookup IDs, custom lookups, and custom non-relationship fields all work. The rejection is specifically for relationship-traversal syntax (`X.Y`, `__r.Y`).
+
+Verified working in dry-run:
+
+| Field | Type | Result |
+|---|---|---|
+| `OwnerId` | standard lookup ID | ✓ deploys |
+| `ParentId` | standard lookup ID | ✓ deploys |
+| `MyAccountManager__c` | custom Lookup → User | ✓ deploys |
+| `Region__c` | custom Text | ✓ deploys |
+| `Status__c` | custom Picklist | ✓ deploys |
+
+Verified rejected:
+
+| Field | Why |
+|---|---|
+| `Owner.Name` | relationship traversal |
+| `Parent.Account.Industry` | multi-hop traversal |
+| `MyLookup__r.Name` | relationship traversal (custom) |
+
+When the user says "include the owner's name in every event," the metadata stores `OwnerId` — CDC enriches the lookup automatically and the consumer resolves the related record from the ID.
+
+## "filter expression has syntax errors: unexpected token: 'WHERE'"
+
+The body of `<filterExpression>` is a SOQL WHERE-clause body — without the `WHERE` keyword.
+
+| Wrong | Right |
+|---|---|
+| `WHERE Status__c != null` | `Status__c != null` |
+| `WHERE Industry IN ('Tech', 'Finance')` | `Industry IN ('Tech', 'Finance')` |
+
+## ChangeEvent entity doesn't exist (for custom objects)
+
+`Foo__ChangeEvent` only exists if `Foo__c` exists. If both are being deployed in the same dry-run, the dry-run validator may flag the member because it validates entity references against the *current* org state, not the post-deploy state. Mitigations:
+
+- Deploy the source object first, then the channel member in a second deploy.
+- Or accept that dry-run will flag this case but a real (non-dry-run) deploy succeeds because MDAPI orders the components correctly.

package/skills/managing-cdc-enablement/references/filter-expressions.md

@@ -0,0 +1,93 @@
+# Filter Expression Reference
+
+The `<filterExpression>` body is a SOQL-WHERE-clause-body — predicate only, no `WHERE` keyword. The platform supports a subset of SOQL grammar for CDC filters; this reference documents what the dry-run deploy verifies.
+
+## Operators by field type
+
+| Field type | Supported operators | Notes |
+|---|---|---|
+| Text | `=`, `!=`, `IN`, `NOT IN`, `LIKE` | `LIKE` accepts `%` wildcard. Quote string literals with single quotes. |
+| Number / Currency / Percent | `=`, `!=`, `<`, `<=`, `>`, `>=` | Numeric literals unquoted. |
+| Boolean (Checkbox) | `=`, `!=` | Use `true` / `false` literal — no quotes. |
+| Date | `=`, `!=` | Named literals (`TODAY`, `THIS_WEEK`, `LAST_N_DAYS:7`) and ISO date strings work. |
+| DateTime | `=`, `!=` only | **Range operators (`>`, `<`) are rejected** — "Only equality operators are supported for this field type or value". |
+| Reference (lookup ID) | `=`, `!=`, `IN`, `NOT IN` | Use the 18-character ID in single quotes: `OwnerId = '005000000000000AAA'`. |
+| Picklist | `=`, `!=`, `IN`, `NOT IN` | Quote the value as a string. |
+
+## Compound expressions
+
+`AND`, `OR`, and parentheses all work. There's no documented limit on nesting depth.
+
+```text
+(Industry = 'Technology' OR Industry = 'Finance') AND AnnualRevenue > 0 AND Phone != null
+```
+
+## Null checks
+
+```text
+Phone = null
+Phone != null
+```
+
+`null` is a literal — no quotes.
+
+`ISBLANK()` and `ISNULL()` are **not** valid filter operators — they parse-fail with "unexpected token". They work in formulas but not in CDC filter expressions. Use `Field = null` / `Field != null` instead.
+
+## Functions
+
+`LOWER(Name) = 'acme'` deploys successfully. Other SOQL functions probably work, but only `LOWER` has been verified in this skill's dataset. Test before relying on `UPPER`, `CONVERTCURRENCY`, etc.
+
+## What the filter cannot do
+
+| Pattern | Deploy error |
+|---|---|
+| `WHERE Industry = 'Tech'` | "filter expression has syntax errors: unexpected token: 'WHERE'" — drop the keyword. |
+| `IsDeleted = false` | "The IsDeleted field in the filter expression is invalid." Soft-deleted records still emit ChangeEvent; you cannot filter them out via this mechanism. |
+| `Owner.Username = 'foo@bar.com'` | "The Owner.Username field in the filter expression is invalid." Relationship traversal works in `<enrichedFields>` rejection messages but NOT in filter expressions either — single-hop only. |
+| `LastModifiedDate > LAST_N_DAYS:30` | "Only equality operators are supported for this field type or value." DateTime is equality-only; for "recent changes" semantics, use `LastModifiedDate = LAST_N_DAYS:N` (which compares to the *day*, not the timestamp). |
+
+## Field-to-field comparison: not supported
+
+The right-hand side of a comparison must be a **literal**. Field references are rejected.
+
+| Wrong | Deploy error |
+|---|---|
+| `BillingCity = ShippingCity` | "syntax errors: unexpected token: 'ShippingCity'" |
+| `NumberOfEmployees > AnnualRevenue` | "unexpected token: 'AnnualRevenue'" |
+
+If the user wants "records where two fields differ," that logic must live downstream of the change event consumer, not in the filter.
+
+## Composite (compound) fields like Address: dotted-component is the only valid form
+
+Counterintuitively, the opposite rule applies for composite fields like `BillingAddress` vs. relationship traversals like `Owner.Name`. Compound fields **require** dot-notation; flat component names are rejected.
+
+| Pattern | Result |
+|---|---|
+| `BillingAddress.City = 'San Francisco'` | ✓ deploys — required form for compound fields |
+| `BillingAddress = null` | ✗ "Compound field BillingAddress has to be used with a component field in a filter expression" |
+| `BillingCity = 'San Francisco'` (flat component) | ✗ "The BillingCity field in the filter expression is invalid" |
+| `BillingState`, `BillingPostalCode`, `BillingCountry`, `BillingLatitude` (flat) | ✗ all rejected as invalid |
+
+So, for the same `BillingAddress` field, the accepted form differs by location:
+
+| Location | `BillingAddress` (compound) | `BillingAddress.City` (dotted) | `BillingCity` (flat component) |
+|---|---|---|---|
+| `<filterExpression>` | ✗ "has to be used with a component field" | ✓ deploys (required form) | ✗ "field is invalid" |
+| `<enrichedFields>` | ✓ deploys | ✗ "isn't valid" (dots never allowed) | ✗ "isn't valid" (components not exposed at this layer) |
+
+Rules per location:
+
+- **Filter expression**: address components are reachable only via dotted form on the compound (`BillingAddress.City`). Both the compound itself (no component) and the flat component name are rejected.
+- **Enrichment field**: takes a top-level field API name only. The compound `BillingAddress` is a top-level field and works; dotted forms are never valid here regardless of whether the dot would be a compound-component select or a relationship traversal; flat components like `BillingCity` are not top-level enrichable fields and are rejected.
+- **Relationship traversal** (`Owner.Name`, `Parent.Industry`) is rejected in both locations.
+
+The mental model: compound fields are a single physical column with sub-components; relationships are joins. The filter parser supports dotted access into compound sub-components but never into joins. The enrichment list takes top-level field names only and never accepts dots; the platform handles compound-vs-component decomposition itself when emitting the change event payload.
+
+## What's NOT yet verified
+
+- Aggregate functions or subqueries — almost certainly unsupported.
+- Operators on Long Text, Rich Text, Encrypted, Geolocation field types.
+- Filter on a custom field that doesn't exist (deploy-time error vs runtime).
+- Custom-object-specific picklist with locale-sensitive values.
+
+If the user requests one of these and the deploy succeeds — update this file. If it fails — capture the error here.

package/skills/managing-suite-assignments/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: managing-suite-assignments
+description: "Manages all forms of test suite assignment for DevOps Center pipeline stages via the Connect API testSuiteStages endpoint. Covers three modes: (A) attaching a single suite to a stage as a one-off add, (B) bulk-mapping multiple suites to a stage as a testing strategy with a mandatory impact-preview table before any changes, and (C) adding or removing individual test classes within a suite assignment with governance rules that exclude rejected tests and re-present the final list before committing. TRIGGER when: a suite is found unlinked from a pipeline stage and the user wants to assign it; the user wants to configure suite-to-stage mappings across a pipeline or assign multiple suites to stages as part of a testing strategy; the user wants to add or remove tests in a suite, sync reviewed tests into a suite, or promote tests to a suite. DO NOT TRIGGER when: authoring new test classes (use generating-apex-test) or running tests directly (use running-apex-tests)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Managing Suite Assignments
+
+## Prerequisites
+
+Load `checking-devops-prerequisites` first — Prerequisites 1–4 AND Prerequisite 5 (stage). You need `doce-org-alias`, `pipelineId`, and `stageId` before proceeding in any mode.
+
+| Variable | Description |
+|---|---|
+| `doce-org-alias` | Established in Prerequisite 1 |
+| `pipelineId` | Identified in Prerequisite 4 (pipeline selection) |
+| `stageId` | Identified in Prerequisite 5 (stage selection) |
+| `event` | `Pre-Promote`, `Post-Promote`, or `Review` |
+
+---
+
+## Mode A — Assign a single suite to a stage
+
+Use this mode when a relevant test suite already exists but is not yet linked to a pipeline stage and the user wants to add it as a single one-off assignment.
+
+**Additional inputs required:**
+
+| Variable | Description |
+|---|---|
+| `testSuiteId` | ID of the suite to assign |
+| `testSuiteName` | Name of the suite (for display in confirmation) |
+
+**Confirmation gate**
+
+**Confirmation required before any API call is made.**
+
+Present the following prompt to the user and wait for an affirmative response:
+
+> "The suite `<testSuiteName>` is not currently assigned to the `<stageName>` stage (`<event>`). Would you like me to assign it now?"
+
+Do not proceed until the user confirms.
+
+**On success**
+
+Report to the user:
+
+> "Suite `<testSuiteName>` has been assigned to the `<stageName>` stage (`<event>`)."
+
+---
+
+## Mode B — Map multiple suites to a stage
+
+Use this mode when configuring suite-to-stage mappings across a pipeline or assigning multiple suites to stages as part of a testing strategy.
+
+**Additional inputs required:**
+
+| Input | Description |
+|---|---|
+| `testSuiteOperations` | List of `{testSuiteId, action: "add"\|"remove"}` |
+
+**MANDATORY IMPACT PREVIEW — Required Before Any Changes**
+
+**Do not call the API until the user has confirmed the preview below.**
+
+Present the full mapping summary and wait for explicit confirmation:
+
+> "Here's the suite mapping I'll apply:
+>
+> | Suite | Stage | Event | Action |
+> |---|---|---|---|
+> | `<suiteName>` | `<stageName>` | `<event>` | Add |
+> | `<suiteName2>` | `<stageName>` | `<event>` | Remove |
+>
+> Confirm to apply all changes?"
+
+Only proceed after the user explicitly confirms.
+
+**On success**
+
+> "Suite mapping applied. `<N>` suite(s) updated for the `<stageName>` stage."
+
+---
+
+## Mode C — Add/remove test classes in a suite
+
+Use this mode when the user wants to add or remove individual test classes within an existing suite assignment, sync reviewed tests into a suite, or promote tests to a suite.
+
+**Additional inputs required:**
+
+| Input | Source |
+|---|---|
+| `testSuiteOperations` | List of `{testSuiteId, action: "add"\|"remove"}` |
+
+**Governance rules**
+
+- **Never call this without explicit approval.** AI-reviewed or modified tests must be re-presented to the user before this call is made.
+- Rejected tests must be EXCLUDED from the payload — do not include them even if they were previously in the suite.
+- If tests were modified during review, re-present the final list of tests before requesting confirmation.
+
+**Confirmation gate**
+
+**REQUIRED — do not skip.** Show the user the full list of changes before calling:
+
+> "I'm about to sync the following changes to the test suite:
+> - **Add:** `<testSuiteName1>`, `<testSuiteName2>`
+> - **Remove:** `<testSuiteName3>`
+> - Stage: `<stageName>` | Event: `<event>`
+>
+> Confirm?"
+
+Only proceed after receiving explicit confirmation.
+
+**On success**
+
+Confirm to the user:
+> "Test suite updated successfully for the `<stageName>` stage."
+
+---
+
+## The system call
+
+All three modes use the same 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"}
+  ]
+}
+```
+
+**Error handling**
+
+Never expose raw API error messages to the user. Map response status codes to the following user-facing 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." |
+
+---
+
+## Related skills
+
+- **`syncing-test-providers`** — use when the suite you want to assign doesn't appear yet; re-syncing the provider pulls in newly added suites.
+- **`recommending-devops-tests`** — use when a suite has not yet been identified and you need a recommendation for which suite to assign.
+- **`configuring-quality-gate`** — use to configure a quality gate on the stage after mapping suites.
+- **`analyzing-test-failures`** — use for failure analysis and suggested improvements to the tests within a suite.

package/skills/polling-test-results/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: polling-test-results
+description: "Polls a DevOps Center async test execution by runId until it completes, fails, or times out — using read-only SOQL on the execution record at provider-specific intervals (Apex 15s/5m, Code Analyzer 10s/3m, Provar UI 60s/20m, Flow 20s/8m) — then surfaces results. Use this skill when a test suite run is in progress and the user is waiting on results, or immediately after running a suite. TRIGGER when: a test suite run is in progress and the user is waiting on results, or immediately after running a suite and a runId is available. DO NOT TRIGGER when: there is no active runId."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# polling-test-results
+
+**Confirmation required:** No — polling is automatic and read-only. No user confirmation gate is needed.
+
+**What it does:** Polls the DevOps Center org for the status of an async test execution until it completes, times out, or fails.
+
+---
+
+## Prerequisites
+
+You need an active `runId` (returned by the `running-devops-test-suite` skill) and the confirmed `doce-org-alias`. If org context is not yet established, load `checking-devops-prerequisites` first (Prerequisites 1–3).
+
+---
+
+## Inputs required
+
+| Input | Source |
+|---|---|
+| `runId` | Returned by the `running-devops-test-suite` skill |
+| `testType` | Derived from the suite's test provider (Apex, Code Analyzer, UI/Provar, Flow) |
+| `doce-org-alias` | Established via `checking-devops-prerequisites` |
+
+## Polling configuration
+
+| Test type | Poll interval | Max wait | Timeout action |
+|---|---|---|---|
+| Apex unit tests | 15 seconds | 5 minutes | Surface runId, offer retry |
+| Code Analyzer | 10 seconds | 3 minutes | Surface runId, offer retry |
+| UI tests (Provar) | 60 seconds | 20 minutes | Surface runId, mark as pending |
+| Flow tests | 20 seconds | 8 minutes | Surface runId, offer retry |
+
+## Poll query
+
+Query the execution record by `runId` on each interval:
+
+```bash
+sf data query \
+  --query "SELECT Id, Status, TestsRan, TestsPassed, TestsFailed, CoveragePercentage FROM DevopsTestExecution WHERE Id = '<runId>' LIMIT 1" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+Check the `Status` field on each poll:
+- `Queued` / `Running` → wait and poll again
+- `Completed` → proceed to result analysis
+- `Failed` → surface error and offer retry or skip
+
+## On timeout
+
+Surface the `runId` to the user:
+> "The test run is taking longer than expected. Your run ID is `<runId>`. You can check the status manually in DevOps Center, or I can keep waiting — what would you prefer?"
+
+Do not automatically retry after timeout. Wait for user instruction.
+
+## On completion
+
+Pass the full result payload to the `analyzing-test-failures` skill for reasoning. Surface `Coverage`, `SuccessCount`, `FailureCount`, and `QualityGateStatus` inline. Do not surface raw JSON to the user.
+
+---
+
+## Related skills
+
+- Runs are started by `running-devops-test-suite` (including its retrigger mode)
+- Failure analysis is handled by `analyzing-test-failures`

package/skills/recommending-devops-tests/SKILL.md

@@ -0,0 +1,137 @@
+---
+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 generating-apex-test) or running sf apex run test directly (use running-apex-tests)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Recommending DevOps Tests
+
+**Type:** Pure reasoning — no system calls beyond the prerequisite data-fetch queries documented below.
+
+**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.
+
+---
+
+## Step 1 — Fetch suite metadata
+
+Before reasoning can begin, fetch the test suite metadata assigned to the Review pipeline stage. This requires two queries.
+
+**1a — Find the Review pipeline stage trigger:**
+
+```bash
+sf data query \
+  --query "SELECT Id FROM DevopsPipelineStageTrigger WHERE TriggerType = 'Review' AND RelatedRecordId = '<pipelineId>'" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+Record the `Id` returned as `<reviewTriggerId>`.
+
+**1b — Fetch suites assigned to that trigger:**
+
+```bash
+sf data query \
+  --query "SELECT Id, TestSuiteId, TestSuite.Name, IsQualityGateEnabled, DevopsQualityGateId FROM DevopsTestSuiteStage WHERE DevopsPipelineStageTriggerId = '<reviewTriggerId>'" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+Each row provides: `TestSuiteId`, `TestSuite.Name`, `IsQualityGateEnabled`, and `DevopsQualityGateId` (when a gate is configured).
+
+> 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.
+
+---
+
+## Reasoning steps
+
+### 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 |
+| `*.flow-meta.xml`, `*.flow` | Flow |
+| `*.java` | Java |
+| `*.js`, `*.html` (LWC paths) | LWC / JavaScript |
+
+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:
+
+| Change type | Match suites whose `testProviderName` contains |
+|---|---|
+| Apex | `Apex` |
+| Flow | `Flow` |
+| Java | `Java` |
+| 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.
+
+### 3 — Rank matched suites
+
+Within each matched provider group, rank suites by:
+1. `triggerType` alignment — `Pre-Promote` suites first for commit-time checks
+2. Quality gate presence — suites with a `qualityGateRuleName` are higher priority (they gate promotion)
+3. Suite name relevance — if the suite name contains a term from the modified file names, boost it
+
+### 4 — Flag new methods with no suite coverage
+
+For any new method added in the diff, flag it as a gap regardless of provider matching:
+> "⚠ `processRefund()` in `OrderService.cls` is a new method. No existing suite can confirm it's covered until tests are authored and linked."
+
+### 5 — Return the recommendation list
+
+Group recommendations by change type so it's clear why each suite was suggested.
+
+---
+
+## Output format
+
+```text
+Recommended suite(s) for this commit:
+
+Apex changes detected (OrderService.cls, InvoiceService.cls):
+1. <SuiteName> — Apex Test Provider | Trigger: Pre-Promote | Gate: <gateName or none>
+2. <SuiteName2> — Apex Test Provider | Trigger: Post-Promote | Gate: <gateName or none>
+
+Flow changes detected (OrderApproval.flow):
+1. <SuiteName3> — Flow Test Provider | Trigger: Pre-Promote | Gate: <gateName or none>
+
+Code Analyzer — Apex rules:
+1. <SuiteName4> — Code Analyzer | Trigger: Pre-Promote | Gate: <gateName or none>
+
+No matching suite found for:
+- LWC changes — no LWC test suite is assigned to this stage
+
+Coverage gaps (new methods — manual authoring required):
+- `processRefund()` in `OrderService.cls` — new method, not yet covered by any suite
+```
+
+---
+
+## v1 constraint
+
+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
+
+- To analyze failures from a run, use `analyzing-test-failures`.
+- To actually execute a recommended suite, use `running-devops-test-suite`.