@salesforce/afv-skills 1.18.0 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

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

@@ -0,0 +1,159 @@
+---
+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 generating-apex) or new test classes authored (use generating-apex-test)."
+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.

package/skills/checking-devops-prerequisites/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: checking-devops-prerequisites
+description: "Validate the environment before any DevOps Center pipeline testing action: confirms an authenticated Salesforce org, the Agentforce DX plugin, an authenticated DevOps Center org, and an identified pipeline (and optionally a pipeline stage). Use this FIRST, internally, from any DevOps testing skill (running a test suite, polling results, syncing tests, configuring or retriggering a quality gate, assigning/mapping suites, creating fix work items, recommending tests, explaining coverage, analyzing failures). TRIGGER when another DevOps testing skill needs to confirm org/pipeline context before a query or system call. DO NOT TRIGGER for non-DevOps-Center work."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Checking DevOps Prerequisites
+
+Shared 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`.
+
+## How other skills use this
+
+Every DevOps testing skill loads this skill first and runs Prerequisites 1–4 in order. Prerequisite 5 (stage) is run **only** when the calling skill operates on a specific pipeline stage (running/retriggering a suite, syncing, configuring a gate, mapping a suite). The calling skill passes back the resolved `doce-org-alias`, `pipelineId`, and (when applicable) `stageId` to use in its own commands.
+
+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 calling skill operates on a specific stage.
+
+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 a calling skill needs it
+
+---
+
+## Error Handling
+
+| 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." |
+
+Never expose raw API errors, stack traces, or JSON error payloads to the user.
+
+## Gotchas
+
+| 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 |
+| 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 |
+| `sf plugins` doesn't match `agentforce` | The installed plugin is `@salesforce/plugin-agent` — match on `plugin-agent` too |

package/skills/configuring-quality-gate/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: configuring-quality-gate
+description: "Creates a DevOps Center quality gate with associated rules (PASS_PERCENTAGE, SEVERITY, ESSENTIAL) and links it to a pipeline-stage suite assignment, after showing a mandatory impact preview and obtaining explicit confirmation. Use this skill when a user wants to set or configure a quality gate, change a coverage threshold, or establish testing benchmarks on a pipeline stage. TRIGGER when: the user wants to set/configure a quality gate, change a coverage threshold, or set testing benchmarks on a stage. DO NOT TRIGGER when: only re-running an existing gate (use running-devops-test-suite in retrigger mode)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+## Prerequisites
+
+Load `checking-devops-prerequisites` first — Prerequisites 1–4 AND Prerequisite 5 (stage). You need `doce-org-alias`, `pipelineId`, `stageId`, and the target `DevopsTestSuiteStage` record Id.
+
+## Inputs required
+
+| Input | Source |
+|---|---|
+| `name` | User-provided name for the quality gate |
+| `rules` | List of `{type, threshold?}` — see rule types below |
+| `doce-org-alias` | Established in Prereq 1 |
+| `testSuiteStageId` | Target `DevopsTestSuiteStage` record Id (Prereq 5) |
+
+## Rule types
+
+| Type | Description | Threshold |
+|---|---|---|
+| `PASS_PERCENTAGE` | Minimum % of tests that must pass | Required (0–100) |
+| `SEVERITY` | Maximum allowed severity level of failures | Required (numeric, e.g. 1–5) |
+| `ESSENTIAL` | All essential tests must pass | Not required |
+
+---
+
+## MANDATORY IMPACT PREVIEW
+
+**Before executing any commands**, show the user this preview and wait for explicit confirmation:
+
+> "Here's what this quality gate will enforce on `<stageName>`:
+> - Rule: `<type>` — `<description>`
+> - Threshold: `<value>`
+> - Affected pipelines: `<list>`
+>
+> Confirm to apply?"
+
+**Never proceed past this point without showing the impact preview first and receiving explicit confirmation.**
+
+---
+
+## Confirmation gate
+
+Only proceed with the steps below after the user has explicitly confirmed (e.g., "yes", "confirm", "go ahead"). If the user declines or does not confirm, stop and do not execute any commands.
+
+---
+
+## Step 1 — Create the gate record
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devopstesting/qualityGate" \
+  --method POST \
+  --body '{"name": "<gateName>"}' \
+  --target-org <doce-org-alias>
+```
+
+Extract `qualityGateId` from the response.
+
+## Step 2 — Create each rule as a sObject record
+
+Rules are not accepted in the Connect API payload — create them as `DevopsQualityGateRule` records directly. Only create rules the user has requested. `ESSENTIAL` has no threshold.
+
+```bash
+sf data create record \
+  --sobject DevopsQualityGateRule \
+  --values "DevopsQualityGateId='<qualityGateId>' Rule='PASS_PERCENTAGE' Threshold=<value>" \
+  --target-org <doce-org-alias> --json
+
+sf data create record \
+  --sobject DevopsQualityGateRule \
+  --values "DevopsQualityGateId='<qualityGateId>' Rule='ESSENTIAL'" \
+  --target-org <doce-org-alias> --json
+
+sf data create record \
+  --sobject DevopsQualityGateRule \
+  --values "DevopsQualityGateId='<qualityGateId>' Rule='SEVERITY' Threshold=<value>" \
+  --target-org <doce-org-alias> --json
+```
+
+## Step 3 — Link the gate to the suite stage
+
+Update the `DevopsTestSuiteStage` record to link the new gate:
+
+```bash
+sf data update record \
+  --sobject DevopsTestSuiteStage \
+  --record-id <testSuiteStageId> \
+  --values "IsQualityGateEnabled=true DevopsQualityGateId='<qualityGateId>'" \
+  --target-org <doce-org-alias> --json
+```
+
+---
+
+## On success
+
+Confirm to the user:
+> "Quality gate `<gateName>` created with `<N>` rule(s) and assigned to `<suiteName>` on `<stageName>`."
+
+## Error handling
+
+Never expose raw API errors. Use the following responses:
+
+| Status | Response |
+|---|---|
+| 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." |
+
+---
+
+## Related skills
+
+- To re-run a gate after meeting threshold, use `running-devops-test-suite` (retrigger mode).
+- To assign or map suites to stages, use `managing-suite-assignments`.

package/skills/configuring-test-provider/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: configuring-test-provider
+description: "Configures an available test provider (e.g. Apex Unit Tests, Code Analyzer, Flow Tests, Provar) on a DevOps Center pipeline via the Connect API, after explicit user confirmation, so the provider's test suites become available for assignment to pipeline stages. Takes a pipelineId and a testProviderId. Use this skill when a provider is available on the pipeline but not yet configured and the user wants to enable it. TRIGGER when: the user wants to configure, enable, set up, or add a test provider on a pipeline, or wants a not-yet-configured provider's suites to become available. DO NOT TRIGGER when: re-syncing an already-configured provider to pick up new suites (use syncing-test-providers), or assigning existing suites to a stage (use managing-suite-assignments)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Configuring a Test Provider
+
+Configures an available test provider on a DevOps Center pipeline, making its test suites available for assignment to pipeline stages.
+
+**Confirmation required:** Yes — explicit confirmation before the provider is configured.
+
+## Prerequisites
+
+Load `checking-devops-prerequisites` first — Prerequisites 1–4 (org login, Agentforce DX plugin, DevOps Center org auth, pipeline identified). Prerequisite 5 (stage) is **not** required: providers are configured at the pipeline level, not the stage level.
+
+| Variable | Source |
+|---|---|
+| `doce-org-alias` | Established in Prerequisite 1 |
+| `pipelineId` | Identified in Prerequisite 4 (pipeline selection) |
+| `testProviderId` | Resolved by fetching the pipeline's test providers (below) |
+
+---
+
+## Step 1 — Fetch test providers to resolve the provider ID
+
+Get all test providers for the pipeline so you can resolve the `testProviderId` and confirm which providers are still available to configure:
+
+```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:
+
+```text
+Test providers for <pipelineName>:
+
+✓ Configured:
+- Code Analyzer (63 suites)
+- Apex Unit Tests (5 suites)
+
+Available (not yet configured):
+- Flow Tests
+```
+
+- **Only an Available provider can be configured.** If the pipeline has no available providers, report that and stop — do NOT fabricate a provider or ID.
+
+### If the named provider is already Configured
+
+Do **not** present the confirmation gate and do **not** POST to the configure endpoint (Steps 2–3) — that would create a duplicate `DevopsPipelineTestProvider`. Instead:
+
+1. State plainly that the provider is already configured, including its synced suite count and last-sync time if returned (e.g. *"Flow Tests is already configured on `<pipelineName>` with 3 suites synced (last sync 2026-06-23)."*).
+2. Diagnose the user's actual goal and redirect **by name**:
+   - If the user says the provider's **suites don't appear when assigning tests to a stage**, this is a **stage-assignment gap, not a provider-configuration gap** — the suites already exist at the pipeline level; they just need to be linked to the stage. Redirect to **`managing-suite-assignments`**.
+   - If the user expects **newly created suites** that aren't yet synced, redirect to **`syncing-test-providers`** (re-sync via `POST /connect/devops/sync`) to pull them in.
+3. Do not loop back to configuring — finish cleanly after the explanation and redirect.
+
+## Step 2 — Confirmation gate
+
+**Required — do not call the API before the user confirms.**
+
+> "I'll configure `<testProviderName>` on the `<pipelineName>` pipeline. This will make its suites available for assignment to stages. Confirm?"
+
+Do not proceed until the user gives an affirmative response.
+
+## Step 3 — Configure the provider
+
+On confirmation, call the configure endpoint with the provider ID:
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devops/pipeline/<pipelineId>/testProvider" \
+  --method POST \
+  --body '{"testProviderId": "<testProviderId>"}' \
+  --target-org <doce-org-alias>
+```
+
+## On success
+
+> "Provider `<testProviderName>` is now configured on the `<pipelineName>` pipeline. Its suites are available for assignment to stages."
+
+Newly configured suites can then be assigned to stages with `managing-suite-assignments`.
+
+---
+
+## Critical gotcha
+
+This `POST .../pipeline/<pipelineId>/testProvider` endpoint **creates a new provider configuration record** (`DevopsPipelineTestProvider`). Use it ONLY to configure a provider for the first time. To re-sync an already-configured provider for new suites, use `syncing-test-providers` (`POST /connect/devops/sync`) — calling this configure endpoint on an already-configured provider produces **duplicate** `DevopsPipelineTestProvider` records.
+
+## Error Handling
+
+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 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." |
+
+---
+
+## Related skills
+
+- **`checking-devops-prerequisites`** — loaded first to establish org and pipeline context.
+- **`syncing-test-providers`** — once a provider is configured, use this to re-sync it later and pull in newly added suites.
+- **`managing-suite-assignments`** — after configuring a provider, use this to assign or map its suites to a pipeline stage.
+- **`recommending-devops-tests`** — to recommend which of the newly available suites to run.

package/skills/creating-fix-work-item/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: creating-fix-work-item
+description: "Creates a DevOps Center WorkItem to track a fix for a test failure or Code Analyzer violation. Before creating anything, it shows a subject/assignee/project preview and requires explicit confirmation. Use this skill when you want to create a fix work item, track a remediation task, or assign a test or analysis failure to a developer. TRIGGER when: the user wants to create a fix work item, log a remediation, or assign a failure to a developer for resolution. DO NOT TRIGGER when: writing the fix code itself (use generating-apex)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+## Prerequisites
+
+Load `checking-devops-prerequisites` first — Prerequisites 1–4. You need `doce-org-alias`, the `DevopsProjectId` to file under, and an `OwnerId` (assignee). If no DevopsProject exists, surface that the work item cannot be created until a project exists.
+
+## Inputs required before creating
+
+| Input | How to obtain |
+|---|---|
+| `DevopsProjectId` | From the pipeline's associated project — query `DevopsProject WHERE Name = '<projectName>'` on the doce org if not already known |
+| `Subject` | Derived from failure analysis — e.g. "Fix: Missing code-analyzer-v5.yml workflow in blitz-10-06 repository" |
+| `OwnerId` | User ID of the developer to assign to — query `SELECT Id, Name FROM User WHERE Username = '<username>'` on the doce org if not known. Ask the user if the username is unknown. |
+| `doce-org-alias` | Established in Prerequisites |
+
+## Confirmation gate
+
+Before creating the work item, show a summary and wait for explicit confirmation:
+
+> "I'll create a fix work item with the following details:
+> - **Subject:** `<subject>`
+> - **Assigned to:** `<assigneeName>`
+> - **Project:** `<projectName>`
+>
+> Shall I create it?"
+
+Do not proceed until the user confirms.
+
+## Creating the work item
+
+```bash
+sf data create record \
+  --sobject WorkItem \
+  --values "Subject='<subject>' DevopsProjectId='<DevopsProjectId>' OwnerId='<OwnerId>'" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+> **Important:** Use `WorkItem` (no namespace) — `DevopsWorkItem` is not a supported sObject in this org version.
+
+## On success
+
+Parse the returned `id` from the result and confirm:
+
+> "Fix work item created (`<id>`): `<subject>`. Assigned to `<assigneeName>` in the `<projectName>` project."
+
+## Error handling
+
+Never expose raw API error messages. Map errors to plain-language responses:
+
+| Error | Response |
+|---|---|
+| `FIELD_INTEGRITY_EXCEPTION` | "The assignee ID is invalid. Let me look up the correct user ID — what's the developer's username?" |
+| `REQUIRED_FIELD_MISSING` | "A required field is missing. Check that `Subject` and `DevopsProjectId` are both provided." |
+| `INSUFFICIENT_ACCESS` | "Your user doesn't have permission to create work items in this project." |
+| Any other error | "The work item could not be created. Error: `<plain summary>`. Try again or create it manually in DevOps Center." |
+
+## Related skills
+
+- `analyzing-test-failures` — provides the failure analysis and improvement suggestions that motivate creating a fix work item