@salesforce/afv-skills 1.25.0 → 1.27.0

package/skills/dx-devops-test-suite-assignments-configure/references/suite-assignment-modes.md

@@ -0,0 +1,99 @@
+# Modes B–D — Assign / Map / Manage Suite Classes
+
+All three modes use the same `testSuiteStages` endpoint (`references/api-endpoint.md`). They differ in scope and the confirmation pattern required.
+
+## Prerequisites & shared inputs
+
+Run Prerequisites 1–4 **and** Prerequisite 5 (stage). You need:
+
+| Variable | Description |
+|---|---|
+| `doce-org-alias` | Prerequisite 1 |
+| `pipelineId` | Prerequisite 4 (pipeline selection) |
+| `stageId` | Prerequisite 5 (stage selection) |
+| `event` | `Pre-Promote`, `Post-Promote`, or `Review` |
+
+---
+
+## Mode B — Assign a single suite to a stage
+
+Use when a relevant test suite already exists but is not yet linked to a stage and the user wants to add it as a single one-off assignment.
+
+**Additional inputs:**
+
+| Variable | Description |
+|---|---|
+| `testSuiteId` | ID of the suite to assign |
+| `testSuiteName` | Name of the suite (for display in confirmation) |
+
+**Confirmation gate (required before any API call):**
+
+> "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:**
+
+> "Suite `<testSuiteName>` has been assigned to the `<stageName>` stage (`<event>`)."
+
+---
+
+## Mode C — Map multiple suites to a stage
+
+Use when configuring suite-to-stage mappings across a pipeline or assigning multiple suites as part of a testing strategy.
+
+**Additional inputs:**
+
+| 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:
+
+> "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 D — Add/remove test classes in a suite
+
+Use 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:**
+
+| 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 before requesting confirmation.
+
+**Confirmation gate (required — do not skip):**
+
+> "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 explicit confirmation.
+
+**On success:**
+
+> "Test suite updated successfully for the `<stageName>` stage."

package/skills/dx-devops-test-suite-run/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: dx-devops-test-suite-run
+description: "Runs DevOps Center test suites on a pipeline stage (Pre-Promote, Post-Promote, or Review event) end to end: triggers async execution via the Connect API after an explicit confirmation gate, then polls by runId at provider-specific intervals until it completes, fails, or times out, and hands results to failure analysis. Also retriggers a quality gate after fixes, but only once coverage meets the threshold. Use this skill when a user wants to run, kick off, or launch test suites on a stage, re-run a quality gate, or watch an in-progress run to completion. TRIGGER when: the user wants to run/launch suites on a stage, execute tests before or after promotion, re-run a quality gate after fixing failures, unblock a blocked promotion after adding tests, or poll/watch an in-progress run. DO NOT TRIGGER when: running sf apex run test directly (use platform-apex-test-run), or configuring a NEW gate or threshold (use dx-devops-test-pipeline-configure)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Run a DevOps Center Test Suite
+
+Triggers a DevOps Center test suite execution and watches it to completion. Running and polling are two halves of one operation — never poll without first having (or being handed) a `runId`.
+
+> **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. Always query the org with `sf data query` or `sf api request rest`.
+
+---
+
+## Prerequisites
+
+Run the prerequisite checks in `references/prerequisite-checks.md` — Prerequisites 1–4 **and** Prerequisite 5 (stage), since this skill operates on a specific stage. You need the confirmed `doce-org-alias`, `pipelineId`, and `stageId`.
+
+## Inputs required
+
+| Input | How to obtain |
+|---|---|
+| `pipelineId` | Prerequisite 4 (pipeline selection) |
+| `stageId` | Prerequisite 5 (pipeline stage confirmation) |
+| `event` | Confirm with user: `Pre-Promote`, `Post-Promote`, or `Review` |
+| `testSuiteIds` | Confirmed suite IDs from selection or recommendation |
+| `doce-org-alias` | Prerequisite 1 |
+
+---
+
+## Step 1 — Trigger execution
+
+### Confirmation gate
+
+**This call mutates org state — do not proceed without explicit user confirmation.** Before calling the API, show:
+
+> "I'm about to run tests with the following configuration:
+> - Pipeline: `<pipelineName>`
+> - Stage: `<stageName>`
+> - Event: `<event>`
+> - Suite(s): `<suiteName(s)>`
+> - Org: `<doce-org-alias>`
+>
+> Shall I proceed?"
+
+Do not make the API call until the user confirms.
+
+### API call
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/stage/execute" \
+  --method POST \
+  --body '{
+    "stageId": "<stageId>",
+    "event": "<event>",
+    "testSuiteIds": ["<suiteId1>", "<suiteId2>"]
+  }' \
+  --target-org <doce-org-alias>
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `stageId` | string | The ID of the pipeline stage to execute tests on |
+| `event` | string | `Pre-Promote`, `Post-Promote`, or `Review` |
+| `testSuiteIds` | string[] | One or more test suite IDs to execute |
+
+### On success
+
+Extract the `runId` (execution ID) from the response. Inform the user:
+
+> "Tests are running in `<doce-org-alias>`. I'll update you when results are ready."
+
+Then proceed **immediately** to Step 2 (polling) with the `runId`.
+
+### On error
+
+See `references/error-handling.md`. If the org rejects execution (e.g. `environmentId: null`, or `classIdList is null or empty — no tests to execute`), read the actual error, explain the root cause and required fix in plain language, and finish cleanly. **Do not retry in a loop and do not fabricate a `runId` or results.**
+
+---
+
+## Step 2 — Poll until completion
+
+**Confirmation required:** No — polling is automatic and read-only.
+
+Poll the execution record by `runId` at the provider-appropriate interval. Full intervals, timeout behavior, and the poll query are in `references/polling-configuration.md`.
+
+Summary of the loop (the `runId` is a `DevopsTestSuiteExecution` Id — poll that object, not `DevopsTestExecution`):
+- Query `DevopsTestSuiteExecution` by `runId` each interval for `Status, Coverage, SuccessCount, FailureCount, QualityGateStatus`.
+- `InProgress` → wait and poll again.
+- `Passed` / `Failed` → surface `Coverage`, `SuccessCount`, `FailureCount`, and `QualityGateStatus` inline (no raw JSON). If `FailureCount > 0`, fetch the child `DevopsTestExecution` failure rows and hand off to **`dx-devops-test-failures-analyze`**.
+- `Error` → the run itself errored (not test failures); surface `ResultDetails`/`Message` in plain language and offer retry or skip.
+- **Timeout** → surface the `runId`, do NOT auto-retry, wait for user instruction.
+
+---
+
+## Retrigger mode (re-running a quality gate)
+
+Use when a promotion was blocked by a gate failure and the coverage gap has since been addressed. **All preconditions, gate, and the retrigger API call are in `references/retrigger-mode.md`.** Key rule: do **not** retrigger unless the latest `Coverage` meets or exceeds the `DevopsQualityGateRule` threshold. After the retrigger returns a new `runId`, hand it to Step 2 (polling).
+
+---
+
+## Related skills
+
+- **`dx-devops-test-failures-analyze`** — receives the failure payload on completion; can also create a fix work item.
+- **`dx-devops-test-suite-assignments-configure`** — recommend which suites to run, or assign a suite to the stage if it isn't linked yet.
+- **`dx-devops-test-pipeline-configure`** — configure a new quality gate or threshold (this skill only re-runs existing gates).

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

@@ -0,0 +1,31 @@
+# Error Handling — Execution & Polling
+
+Never expose raw API errors, stack traces, or JSON payloads to the user.
+
+## Step 1 — Execute call
+
+| Status | Message to user |
+|---|---|
+| 400 | "The test execution request was invalid. Check that the stage and suite IDs are correct." |
+| 403 | "You don't have permission to run tests on this pipeline. Check your DevOps Testing API access." |
+| 404 | "The pipeline or stage was not found. It may have been deleted." |
+| 500 | "The DevOps Center org returned a server error. Try again in a few minutes." |
+
+## Org-side execution rejections (read the real error, explain, finish — do NOT loop)
+
+| Org error | Explanation to user |
+|---|---|
+| `environmentId: null` | "The environment connection isn't resolving for this stage. Re-authenticate or reconnect the stage's environment in DevOps Center, then try again." |
+| `classIdList is null or empty — no tests to execute` | "The assigned suite(s) contain no test classes, so there's nothing to run. Add test classes to the suite (via dx-devops-test-suite-assignments-configure) and try again." |
+
+In both cases: attempt the call once, explain the root cause and required fix, finish cleanly. Do NOT retry in a loop and do NOT fabricate a `runId` or results.
+
+**Empty-org / no-data case:** If the stage has no assigned suites, report that clearly and do NOT call the execute endpoint or fabricate a suite/run.
+
+## Step 2 — Polling
+
+If no `DevopsTestExecution` record matches the runId, report it gracefully and do not fabricate result data. On timeout, surface the runId and wait for user instruction — never auto-retry.
+
+## Do NOT use `sf apex run test`
+
+That command is for the `platform-apex-test-run` skill, not DevOps Center test suites.

package/skills/dx-devops-test-suite-run/references/polling-configuration.md

@@ -0,0 +1,78 @@
+# Polling Configuration (Step 2)
+
+**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` (from Step 1, the execute call) and the confirmed `doce-org-alias`. If org context is not yet established, run Prerequisites 1–3 (`references/prerequisite-checks.md`).
+
+## Inputs
+
+| Input | Source |
+|---|---|
+| `runId` | Returned by the Step 1 execute call (or supplied by the user for an in-progress run) |
+| `testType` | Derived from the suite's test provider (Apex, Code Analyzer, UI/Provar, Flow) |
+| `doce-org-alias` | Established via prerequisites |
+
+If the user is watching an already-running execution, resolve the `runId` by querying the most recent `DevopsTestExecution` for the relevant trigger, or use the runId the user provides.
+
+## Polling intervals
+
+| 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 |
+
+## Object model — read the right object
+
+The `runId` returned by the execute call is a **`DevopsTestSuiteExecution`** record Id (the suite-level run). Poll *that* object — it holds the status and the aggregate results. Per-test detail lives on child `DevopsTestExecution` records linked by `DevopsTestSuiteExecutionId`.
+
+| Object | Role | Key fields |
+|---|---|---|
+| `DevopsTestSuiteExecution` (poll this) | Suite-level run = the `runId` | `Status`, `Coverage`, `SuccessCount`, `FailureCount`, `SuccessRate`, `FailureRate`, `QualityGateStatus`, `ExecutionEndTime`, `ResultDetails`, `ReportUrl` |
+| `DevopsTestExecution` (per-test detail) | One row per test, linked via `DevopsTestSuiteExecutionId` | `Status`, `Message`, `Severity`, `ResultDetails`, `DevopsTestId` |
+
+> Do NOT query `TestsRan`, `TestsPassed`, `TestsFailed`, or `CoveragePercentage` — those fields do not exist on either object and the query will fail with `INVALID_FIELD`. Use the field names in the table above.
+
+## Poll query
+
+Query the suite execution record by `runId` on each interval:
+
+```bash
+sf data query \
+  --query "SELECT Id, Status, Coverage, SuccessCount, FailureCount, QualityGateStatus FROM DevopsTestSuiteExecution WHERE Id = '<runId>' LIMIT 1" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+Check the `Status` picklist on each poll (valid values: `Passed`, `Failed`, `InProgress`, `Error`):
+- `InProgress` → wait and poll again
+- `Passed` → run completed successfully; surface results
+- `Failed` → run completed with test failures; surface results, then fetch per-test detail (below) and hand off to analysis
+- `Error` → the run itself errored (not a test failure); surface the `ResultDetails`/`Message` in plain language 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
+
+When `Status` is `Passed` or `Failed`, surface `Coverage`, `SuccessCount`, `FailureCount`, and `QualityGateStatus` from the `DevopsTestSuiteExecution` record inline (no raw JSON).
+
+If `FailureCount > 0` (or `Status = Failed`), fetch the per-test failure detail from the child `DevopsTestExecution` records, then pass that payload to the **`dx-devops-test-failures-analyze`** skill:
+
+```bash
+sf data query \
+  --query "SELECT Id, Status, Message, Severity, ResultDetails, DevopsTestId FROM DevopsTestExecution WHERE DevopsTestSuiteExecutionId = '<runId>' AND Status = 'Failed'" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+**Empty / no-data case:** If no `DevopsTestSuiteExecution` record matches the runId, report that clearly and do NOT fabricate a runId, status, or result values.

package/skills/dx-devops-test-suite-run/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-suite-run/references/retrigger-mode.md

@@ -0,0 +1,51 @@
+# Retrigger Mode — Re-running a Quality Gate
+
+Use this mode when a promotion was blocked by a quality gate failure and the coverage gap has since been addressed.
+
+## Extra preconditions — all must be true before proceeding
+
+1. The `Coverage` field on the latest `DevopsTestSuiteExecution` meets or exceeds the threshold defined in the `DevopsQualityGateRule`.
+2. The user has explicitly asked to retrigger the gate.
+3. The same `pipelineId`, `stageId`, and `event` from the blocked promotion are known.
+
+If coverage is still below threshold, do **not** retrigger. Instead respond:
+
+> "Coverage is still at `<X>%`, below the `<threshold>%` gate. The gate cannot be retriggered until the threshold is met. Here are the remaining uncovered methods: `<list>`."
+
+Do not retry. Explain what must be resolved first and stop.
+
+## Inputs required for retrigger
+
+| Input | Source |
+|---|---|
+| `pipelineId` | From the blocked promotion context |
+| `stageId` | From the blocked promotion context |
+| `event` | Same event type that originally blocked (`Pre-Promote` or `Post-Promote`) |
+| `suiteIds` | Same suites that were originally run |
+| `doce-org-alias` | Prerequisite 1 |
+
+## Confirmation gate (retrigger)
+
+Before executing the API call, present this confirmation prompt and wait for explicit user approval:
+
+> "Coverage is confirmed at `<X>%`, which meets the `<threshold>%` gate. I'll retrigger the quality gate check for the `<stageName>` stage (`<event>`). Confirm?"
+
+Only proceed after the user confirms. If the user declines, stop without making any API call.
+
+## API call (retrigger)
+
+Uses the same Connect API stage/execute endpoint:
+
+```bash
+sf api request rest "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/stage/execute" --method POST --body '{"stageId":"<stageId>","event":"<event>","testSuiteIds":["<suiteId1>"]}' --target-org <doce-org-alias>
+```
+
+After the call returns a `runId`, hand off to Step 2 (polling) with the new `runId` to monitor the execution result.
+
+## Error handling (retrigger)
+
+If the API returns an error indicating the gate cannot be retriggered, respond with:
+
+> "The quality gate cannot be retriggered right now. Reason: `<plain-language summary>`. Here's what needs to be resolved first: `<list>`."
+
+Never expose raw API error details to the user.

package/skills/analyzing-test-failures/SKILL.md

@@ -1,159 +0,0 @@
----
-name: analyzing-test-failures
-description: "Parses a DevOps Center test-failure or Code Analyzer violation payload and explains it in plain language — failure category, offending file/class/method/line, rule violated, and fix direction — then gives prioritized test-improvement suggestions (distinguishing test-code from production-code fixes). Pure reasoning: no system calls or code authoring. TRIGGER when: a test run failed and the user wants root cause; a quality gate failure needs explaining; Code Analyzer violations need translating to plain language; the user shares a failure payload and asks how to address it; tests keep failing and the user wants suggestions; or the user wants to close coverage gaps, strengthen assertions, or fix flaky/weak tests. DO NOT TRIGGER when: the user wants fix code written (use platform-apex-generate) or new test classes authored (use platform-apex-test-generate)."
-metadata:
-  version: "1.0"
-  minApiVersion: "67.0"
----
-
-# analyzing-test-failures
-
-**Type:** Pure reasoning — no system calls, no code authoring.
-
-**What it does:** Parses a test failure or Code Analyzer violation payload and produces a plain-language explanation, then follows up with concrete, prioritized improvement suggestions per failed test — including whether each fix belongs in the test or in production code. Never exposes raw JSON, stack traces, or API error bodies to the user.
-
----
-
-## Prerequisites
-
-If you need to fetch the failure payload yourself rather than receiving it, load `checking-devops-prerequisites` first, then use `polling-test-results` to obtain the execution result. If the payload is already in context, no prerequisites are needed — this is pure reasoning.
-
----
-
-## Inputs
-
-- JSON failure payload provided by the `polling-test-results` skill, or pasted directly into context from a test run or Code Analyzer execution. Specifically required per failed test:
-  - Test method name
-  - Failure message (the assertion error or exception text)
-  - Failure category (assertion failure, unhandled exception, timeout, compile error)
-
----
-
-## Empty-org / no-data case
-
-If the payload contains no failures or violations, report that clearly (e.g. "No failures found in the provided execution results.") and stop. Do NOT fabricate failures, violations, or improvement suggestions when none are present.
-
----
-
-## Reasoning steps
-
-1. Determine the failure category:
-
-   | Category | Description |
-   |---|---|
-   | **Assertion failure** | A test assertion failed (expected vs actual mismatch) |
-   | **Exception** | An unhandled exception was thrown |
-   | **Code Analyzer violation** | A static analysis rule was violated (e.g. `ApexCRUDViolation`, `ApexSharingViolations`) |
-   | **Timeout** | Test exceeded execution time limit |
-   | **Compile error** | Class failed to compile |
-
-2. For each failure, extract and translate to plain language:
-   - Offending file and class name
-   - Method name
-   - Line number
-   - What rule or assertion was violated, in plain language
-   - Suggested fix direction (without writing code)
-
-3. Group failures by category if more than one.
-
----
-
-## Output format
-
-```text
-Test failure summary:
-
-<N> failure(s) found:
-
-1. [<Category>] `<ClassName>.cls` — `<methodName>()` at line <N>
-   What happened: <plain-language description>
-   Rule violated: <ruleName or assertion description>
-   Fix direction: <plain-language suggestion>
-
-2. [<Category>] `<ClassName2>.cls` — `<methodName2>()` at line <N>
-   ...
-```
-
----
-
-## Code Analyzer violations
-
-For violations, always include:
-- The rule name translated to plain English (e.g. "ApexCRUDViolation" → "A SOQL query was made without checking object-level permissions first")
-- The exact line number
-- The fix direction (e.g. "Add a `Schema.sObjectType.Account.isAccessible()` check before the query")
-
----
-
-## Plain-language rule
-
-Never paste raw stack traces, JSON payloads, or internal Salesforce error codes into the output. Always translate to file name, method, line, and plain description.
-
----
-
-## Suggesting improvements
-
-Invoke this section **after test execution completes with failures**, not on static source code. The failure message is the primary signal — it describes what the test expected vs. what actually happened, which directly informs what the test needs to handle better.
-
-### 1 — Read each failure message
-
-For each failed test in the execution result, extract:
-- Test method name
-- Failure message (the assertion error or exception message)
-- Failure category (assertion failure, unhandled exception, timeout, compile error)
-
-### 2 — Infer what the test is not handling
-
-Reason over the failure message to identify the root cause pattern:
-
-| Failure pattern | Improvement suggestion |
-|---|---|
-| `NullPointerException` | The test is not handling null input — add a null check or a test setup that ensures the data exists |
-| `Assertion failed: expected X but was Y` | The expected value in the assertion is wrong or the test data setup does not produce the right state |
-| `List has no rows for assignment` | The test is querying for data that doesn't exist — test setup is incomplete |
-| `System.LimitException: Too many SOQL queries` | The test is hitting governor limits — the code under test or test setup is making too many queries |
-| `Insufficient access rights on cross-reference id` | The test user lacks the required permissions — the test needs to run as a user with appropriate profile/permission set |
-| `DML currently not allowed` | The test is performing DML inside a method called from a context that doesn't allow it |
-| Code Analyzer violation message | The production code violates a specific rule — the test exposed it but the fix is in the production code, not the test |
-
-### 3 — Produce actionable suggestions
-
-For each failure, describe in plain language:
-- What the failure reveals about what the test is not handling
-- What specifically should be added or changed to make the test robust
-- Whether the fix is in the **test** (assertion, setup, permissions) or in the **production code** (the test is correct but the code under test is broken)
-
-Do not rewrite the test. Only describe what needs to change and why.
-
-### Output format for improvements
-
-```text
-Test improvement suggestions based on execution results:
-
-`<testMethodName>()` — [Assertion Failure / Exception / etc.]
-Failure: "<failure message>"
-What this reveals: <plain-language explanation>
-Suggestion: <specific, actionable recommendation>
-Fix location: Test | Production code
-
-`<testMethodName2>()` — [NullPointerException]
-Failure: "Attempt to de-reference a null object"
-What this reveals: The test is calling the method without setting up the required input data
-Suggestion: Add test data setup for <object/field> before calling the method
-Fix location: Test
-
-Overall: <N> improvement(s) across <M> failed test(s).
-```
-
-### Test fix vs. production-code fix
-
-Suggestions flagged as **Fix location: Production code** indicate a code defect exposed by the test — the test logic itself is sound. These should not block suite promotion on the grounds of test quality; they should be tracked separately as production defects.
-
-Suggestions flagged as **Fix location: Test** indicate the test needs to be hardened — missing setup, wrong assertions, inadequate coverage of edge cases (null inputs, bulk record volumes, mixed permission contexts, governor-limit boundaries).
-
----
-
-## Related skills
-
-- **`polling-test-results`** — obtains the failure payload that feeds into this skill.
-- **`creating-fix-work-item`** — use to create a tracked fix item from the analysis output or to track an approved improvement suggestion as a work item once the user decides to act on it.