@salesforce/afv-skills 1.24.0 → 1.26.0

package/package.json

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

package/skills/commerce-b2b-open-code-components-replace/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: commerce-b2b-open-code-components-replace
+description: "Replace OOTB (out-of-the-box) B2B Commerce components with open source equivalents in site metadata content.json files, or look up the equivalent open code `site:` component for OOTB definitions. Use when users mention \"replace OOTB components\", \"replace commerce components with open code\", \"swap OOTB for open source\", \"replace commerce_builder:\", \"replace OOTB in site\", \"replace component in site metadata\", \"replace component definition\", \"find open code equivalent\", \"equivalent open code component\", \"OOTB to open code mapping\", \"what is the site component for\", components \"in this view\" or \"for a given view\", or a specific list of component names — and want to update or only discover mappings in their store metadata."
+allowed-tools: Bash(grep:*) Bash(ls:*) Read Write
+metadata:
+  version: "1.0"
+---
+
+# Replacing OOTB B2B Commerce Components with Open Code
+
+This skill replaces OOTB (out-of-the-box) B2B Commerce component definitions in site metadata `content.json` files with their open source `site:` equivalents, or looks up the equivalent open code component for given OOTB definitions without making changes. It uses an authoritative mapping loaded from `assets/ootb-to-open-code-mapping.json`.
+
+## Scope
+
+**Modes:** **Full replace** runs the scan (Step 1), user selection if needed, then `content.json` updates (Step 2–3). **Lookup only** (user asks for equivalents but not to change files): apply the mapping-authority rule and report OOTB → `site:` for the named components or for definitions found in the scoped `content.json` — **do not** call Write unless the user confirms replacement. **View-scoped** work: limit file discovery and reads to `sfdc_cms__view/<ViewName>/` (or the path the user gives) instead of all views.
+
+---
+
+## Prerequisites
+
+### Resolve `<package-dir>`
+
+Read `sfdx-project.json` and pick the active package directory. Extract `packageDirectories[]` and use the entry with `"default": true`; if no entry is flagged default, use the first entry. Use this value as `<package-dir>` everywhere below. If `sfdx-project.json` is missing or has no `packageDirectories`, tell the user and abort.
+
+### Delegate setup
+
+Before replacing components, delegate to the **commerce-b2b-open-code-components-integrate** skill to ensure:
+
+1. Open source repository is cloned at `.tmp/b2b-commerce-open-source-components`
+2. Store is selected and site metadata is retrieved locally
+3. Open code components are copied to the store's site metadata
+
+The integrating skill owns the `.tmp/` clone lifecycle (it prompts the user to reuse or re-clone an existing checkout); this skill assumes the clone is already present.
+
+Send a plain-text chat reply to the user (per Rule 1): "Before replacing components, I need to verify that the open code components are set up in your store. Let me check..."
+
+If any prerequisite is not met, the integrating skill will handle it. Once all checks pass, proceed to the replacement workflow.
+
+**Required state** after prerequisites:
+- **Package dir** — the value resolved above (e.g., `force-app`)
+- **Store name** — e.g., `My_B2B_Store1`
+- **Site metadata path** — `<package-dir>/main/default/digitalExperiences/site/<store-name>/`
+
+---
+
+## Replacement Workflow
+
+### Step 1: Scan Site and Cross-Reference Mapping
+
+**This step is MANDATORY.** Always scan the site first before attempting any replacements.
+
+Send a plain-text chat reply to the user (per Rule 1): "I'm scanning your store's site metadata to find all OOTB commerce components currently in use and checking which have open code equivalents."
+
+**Step 1a — Find affected files** (one command, simple literal match):
+
+```bash
+grep -rl '"commerce' \
+  <package-dir>/main/default/digitalExperiences/site/<store-name>/sfdc_cms__view/ \
+  <package-dir>/main/default/digitalExperiences/site/<store-name>/sfdc_cms__themeLayout/ \
+  --include="content.json"
+```
+
+**Step 1b — Read the mapping and parse the matched files.** Read `assets/ootb-to-open-code-mapping.json` once into memory. Then, using the **Read** tool, parse each matched file and extract all `"definition"` values that start with `commerce` (e.g., `commerce_builder:cartBadge`). Collect a deduplicated list of OOTB components across all files.
+
+**Step 1c — List repo components** (one command):
+
+```bash
+ls .tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/
+```
+
+Using the parsed definitions, the `ls` output, and the mapping table, categorize every discovered OOTB component into three groups:
+
+**Show the user a breakdown and a selectable list:**
+
+First, inform the user about skipped and unmapped components:
+```text
+Found X OOTB components in your site:
+
+In mapping table but NOT in repo (skipping):
+  - commerce_builder:quoteSummary → site:quoteSummary (not found in repo)
+
+No mapping available (not in mapping table):
+  - commerce_builder:actionButtons
+  - commerce_builder:layoutHeaderOne
+  - commerce_builder:searchInputContainer
+  - commerce_builder:myAccountMegaMenu
+```
+
+Then present the replaceable components as a **multi-select list** so the user can pick from checkboxes instead of typing. Include an "All of the above" option:
+
+```text
+Which components would you like to replace?
+
+☐ commerce_builder:heading → site:productHeading
+☐ commerce_builder:cartBadge → site:cartBadge
+☐ commerce_builder:searchInput → site:searchInput
+☐ All of the above
+```
+
+If user provided specific component name(s) in the original request, pre-filter to those and skip the selection prompt.
+
+### Step 2: Replace in content.json
+
+Send a plain-text chat reply to the user (per Rule 1): "I'm now replacing the selected OOTB component definitions with their open code equivalents in your site's content.json files."
+
+The affected files are already known from Step 1. For each file that contains selected components:
+1. Use the **Read** tool to read the file
+2. For each selected OOTB component, confirm again that the mapped **`site:`** target exists in the open code repo. Only proceed with replacements that pass this check.
+3. Replace all matching `"definition"` values with their mapped open code equivalents — **always** use the exact `site:<name>` string from the mapping table
+   - Example: `"definition": "commerce_builder:heading"` → `"definition": "site:productHeading"`
+4. Use the **Write** tool to save the updated file
+5. Preserve all other JSON properties — only `"definition"` values change
+
+**Batch efficiently:** if a file contains multiple OOTB components, apply ALL replacements in a single Read → modify → Write pass. Do NOT read and write the same file multiple times.
+
+### Step 3: Report
+
+```text
+✅ Replacement Complete!
+
+Replaced X components across Y files:
+- commerce_builder:heading → site:productHeading (3 files)
+- commerce_builder:cartBadge → site:cartBadge (2 files)
+- commerce_builder:searchInput → site:searchInput (4 files)
+
+Skipped (not in repo):
+- commerce_builder:quoteSummary
+
+No mapping available (left unchanged):
+- commerce_builder:actionButtons
+- commerce_builder:layoutHeaderOne
+- commerce_builder:searchInputContainer
+
+Modified files:
+- sfdc_cms__view/Home/content.json
+- sfdc_cms__view/Product_Detail/content.json
+- sfdc_cms__themeLayout/DefaultTheme/content.json
+
+Next Steps:
+1. Deploy: sf project deploy start -d <package-dir>/main/default/digitalExperiences/site/<store-name>
+2. Test the store thoroughly in Experience Builder
+3. Publish your site when ready
+```
+
+---
+
+## Example Interaction
+
+**User:** "Replace OOTB components with open code versions"
+
+**Agent:** "Before replacing components, I need to verify that the open code components are set up in your store. Let me check..."
+- ✓ Open source repo cloned
+- ✓ Store metadata available for My_B2B_Store1
+- ✓ Open code components are integrated
+
+**Agent:** "I'm scanning your store's site metadata to find all OOTB commerce components and checking which have open code equivalents."
+
+_(Runs grep -rl to find files with commerce definitions, Reads those files to extract component names, runs ls to list repo components, then cross-references with mapping table)_
+
+```text
+Found 8 OOTB components in your site:
+
+No mapping available (not in mapping table):
+  - commerce_builder:searchInputContainer
+  - commerce_builder:layoutHeaderOne
+  - commerce_builder:myAccountMegaMenu
+  - commerce_builder:actionButtons
+```
+
+**Agent** _(asks the user via a multi-select prompt):_
+```text
+Which components would you like to replace?
+
+☐ commerce_builder:heading → site:productHeading
+☐ commerce_builder:cartBadge → site:cartBadge
+☐ commerce_builder:searchInput → site:searchInput
+☐ commerce_builder:cartSummary → site:cartSummary
+☐ All of the above
+```
+
+**User:** _(selects heading and cartBadge)_
+
+**Agent:** "I'm now replacing the selected OOTB component definitions with their open code equivalents in your site's content.json files."
+
+_(Files already known from scan — one Read/Write pass per affected file, all replacements batched)_
+
+```text
+✅ Replacement Complete!
+
+Replaced 2 components across 5 files:
+- commerce_builder:heading → site:productHeading (3 files)
+- commerce_builder:cartBadge → site:cartBadge (2 files)
+
+No mapping available (left unchanged):
+- commerce_builder:searchInputContainer
+- commerce_builder:layoutHeaderOne
+- commerce_builder:myAccountMegaMenu
+- commerce_builder:actionButtons
+
+Modified files:
+- sfdc_cms__view/Home/content.json
+- sfdc_cms__view/Product_Detail/content.json
+- sfdc_cms__themeLayout/DefaultTheme/content.json
+
+Next Steps:
+1. Deploy: sf project deploy start -d force-app/main/default/digitalExperiences/site/My_B2B_Store1
+2. Test the store thoroughly in Experience Builder
+```
+
+---
+
+## Rules
+
+1. **Always explain in chat before executing.** Before every Bash or Write tool call, send a plain-text reply in the conversation that says what the command will do and why. The explanation MUST appear as a normal chat message preceding the tool call. Do NOT embed it inside the command itself (no `echo` lines, no `#` comments), do NOT prefix it to the command, and do NOT rely solely on the tool's `description` parameter — that field is not guaranteed to be visible to the user. After the explanation, issue the tool call and wait for the user to approve it before continuing.
+2. **`assets/ootb-to-open-code-mapping.json` is the only source of truth.** Every OOTB → open-code mapping comes from that file; never guess, infer, or hallucinate component names. Each replacement's new `"definition"` MUST be the exact mapped value from the file, which always uses the `site:` namespace (e.g. `site:productHeading`). Before writing, verify the mapped target exists in the cloned open code components repo (under `.tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/`); if it is not present, skip the replacement and report it under "not in repo".
+3. **Use Read and Write tools for JSON files.** Use the Read tool to parse `content.json` files and the Write tool to update them. Do NOT use bash to parse or edit JSON — no sed, awk, perl, or regex on JSON content. Bash is only for **simple file discovery** (`grep -rl`, `find`, `ls`) — never for extracting or modifying JSON values.
+4. **Minimize commands.** Batch work into as few commands as possible. Use a single grep to scan all files, a single ls to verify the repo, and one Read/Write pass per file. Do NOT run a separate command for every component or every directory.
+
+---
+
+## Error Handling
+
+| Error | Message | Action |
+|-------|---------|--------|
+| Prerequisites not met | "Open code components are not integrated yet." | Run integrating skill first |
+| No mapping found | "No mapping found for '{component}'." | Show available mappings, report as unmapped |
+| Component not in repo | "Open code component '{name}' not found in cloned repo." | Skip and inform user |
+| No OOTB components in site | "No OOTB commerce components found in site metadata." | Inform user, nothing to replace |
+| No replaceable components | "All OOTB components found are unmapped — none can be replaced." | Show the unmapped list, suggest checking for updated mappings |
+| content.json parse error | "Failed to parse content.json: {file}" | Show error, skip file, continue with remaining files |
+
+---
+
+## Verification Checklist
+
+- [ ] Prerequisites verified via integrating skill (repo, store, components)
+- [ ] Site scanned + repo verified + mapping cross-referenced in minimal commands (Step 1)
+- [ ] Each replacement uses the exact mapped `site:` definition and was verified present in the open code repo before write
+- [ ] Breakdown shown to user with three categories before proceeding
+- [ ] User selected components to replace (or provided names)
+- [ ] Each `content.json` file updated in a single Read → modify → Write pass
+- [ ] JSON structure preserved, no syntax errors introduced
+- [ ] User informed of skipped and unmapped components
+- [ ] Deployment command provided

package/skills/commerce-b2b-open-code-components-replace/assets/ootb-to-open-code-mapping.json

@@ -0,0 +1,66 @@
+{
+  "commerce_builder:actionButton": "site:commonButton",
+  "commerce_builder:b2bCartContents": "site:cartB2bCartContents",
+  "commerce_builder:cartAppliedPromotion": "site:cartPromotionApplied",
+  "commerce_builder:cartApplyCoupon": "site:cartApplyCoupon",
+  "commerce_builder:cartBadge": "site:cartBadge",
+  "commerce_builder:cartPromotions": "site:cartPromotions",
+  "commerce_builder:cartSummary": "site:cartSummary",
+  "commerce_builder:checkoutButton": "site:checkoutButton",
+  "commerce_builder:checkoutDeliveryAddress": "site:checkoutDeliveryAddress",
+  "commerce_builder:checkoutDeliveryMethod": "site:checkoutDeliverymethod",
+  "commerce_builder:checkoutGiftOptions": "site:checkoutGiftOptions",
+  "commerce_builder:checkoutNotification": "site:checkoutNotification",
+  "commerce_builder:checkoutPurchaseOrder": "site:checkoutPurchaseOrder",
+  "commerce_builder:checkoutShippingInstructions": "site:checkoutShippingInstructions",
+  "commerce_builder:checkoutSubscriptionPolicyDisclaimer": "site:checkoutSubscriptionPolicyDisclaimer",
+  "commerce_builder:consentBlanket": "site:legalConsentBlanket",
+  "commerce_builder:countryPickerV2": "site:commonCountryPicker",
+  "commerce_builder:drilldownNavigation": "site:commonDrilldownNavigation",
+  "commerce_builder:formattedCurrency": "site:commonFormattedCurrency",
+  "commerce_builder:heading": "site:productHeading",
+  "commerce_builder:layoutFooter": "site:layoutFooter",
+  "commerce_builder:layoutHeaderSimple": "site:layoutHeaderSimple",
+  "commerce_builder:linkList": "site:commonLinksList",
+  "commerce_builder:myAccountAddressContainer": "site:myaccountAddress",
+  "commerce_builder:navigationMenuItemList": "site:myaccountNavigationMenuItems",
+  "commerce_builder:orderConfirmationBillingDetails": "site:orderConfirmationDetailsBilling",
+  "commerce_builder:orderConfirmationDeliveryGroup": "site:orderConfirmationDeliverygroup",
+  "commerce_builder:orderConfirmationErrorMessage": "site:orderConfirmationMessageError",
+  "commerce_builder:orderConfirmationSuccessMessage": "site:orderConfirmationMessageSuccess",
+  "commerce_builder:orderDetails": "site:orderDetails",
+  "commerce_builder:orderList": "site:orderList",
+  "commerce_builder:orderListDateFilter": "site:orderListDateFilter",
+  "commerce_builder:orderProductsInfo": "site:orderProducts",
+  "commerce_builder:orderPromotionsSummary": "site:orderPromotions",
+  "commerce_builder:orderShipmentTracker": "site:orderShipmentTracker",
+  "commerce_builder:paymentByExpress": "site:paymentByExpress",
+  "commerce_builder:productAttachments": "site:productAttachments",
+  "commerce_builder:productBundle": "site:productBundle",
+  "commerce_builder:productBundleItem": "site:productBundleItem",
+  "commerce_builder:productFieldsTable": "site:productFieldsTable",
+  "commerce_builder:productFrequentlyBoughtTogether": "site:productFrequentlyBoughtTogether",
+  "commerce_builder:productMediaGallery": "site:productMediaGallery",
+  "commerce_builder:productPricingDetails": "site:productPricingDetails",
+  "commerce_builder:productSellingModelSelector": "site:productSellingmodelSelector",
+  "commerce_builder:productSet": "site:productSet",
+  "commerce_builder:promotionDiscountsApproaching": "site:promotionDiscountsApproaching",
+  "commerce_builder:purchaseOptions": "site:productPurchaseOptions",
+  "commerce_builder:purchasedProducts": "site:productListPurchased",
+  "commerce_builder:quickOrder": "site:orderQuickOrder",
+  "commerce_builder:quoteSummary": "site:quoteSummary",
+  "commerce_builder:searchFilters": "site:searchFilters",
+  "commerce_builder:searchInput": "site:searchInput",
+  "commerce_builder:searchNoResultsLayout": "site:searchResultsLayoutEmpty",
+  "commerce_builder:searchResults": "site:searchResults",
+  "commerce_builder:searchResultsLayout": "site:searchResultsLayout",
+  "commerce_builder:searchSortMenu": "site:searchSortMenu",
+  "commerce_builder:socialLinks": "site:commonLinksSocial",
+  "commerce_builder:splitShipmentHeader": "site:cartSplitshipmentHeader",
+  "commerce_builder:stickyContainer": "site:commonContainerSticky",
+  "commerce_builder:subscriptions": "site:productSubscriptions",
+  "commerce_builder:userProfileMenu": "site:myAccountUserProfileMenu",
+  "commerce_builder:variantSelector": "site:productVariantSelector",
+  "commerce_builder:wishlist": "site:productWishlist",
+  "commerce_builder:wishlistShortcut": "site:productWishlistShortcut"
+}

package/skills/dx-devops-test-failures-analyze/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: dx-devops-test-failures-analyze
+description: "Analyzes DevOps Center test failures and Code Analyzer violations in plain language — failure category, offending file/class/method/line, rule violated, fix direction, and prioritized improvement suggestions (test-code vs production-code) — then optionally creates a tracked fix WorkItem on explicit request. Analysis is pure reasoning; work-item creation is a confirmation-gated write. Use this skill to explain failures or improvement suggestions, translate Code Analyzer violations, or track a fix as a work item. TRIGGER when: a run failed and the user wants root cause; a quality gate failure needs explaining; violations need translating; the user shares a failure payload and asks how to address it; wants to strengthen tests; or wants to create a fix work item, log a remediation, or assign a failure. 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"
+---
+
+# Analyze DevOps Center Test Failures
+
+Parses a test failure or Code Analyzer violation payload, explains it in plain language, produces prioritized improvement suggestions, and — only on explicit user request — creates a tracked fix work item. Parts 1–2 are pure reasoning (no writes); Part 3 is an optional, confirmation-gated write.
+
+**Never expose raw JSON, stack traces, or internal Salesforce error codes to the user.** Always translate to file name, method, line, and plain description.
+
+---
+
+## Prerequisites
+
+- **Parts 1–2 (analysis):** If the failure payload is already in context, no prerequisites are needed — this is pure reasoning. If you must fetch the payload yourself, run prerequisites (`references/prerequisite-checks.md`, Prereqs 1–4) and obtain the execution result via `dx-devops-test-suite-run` (its polling step).
+- **Part 3 (work item):** Run Prerequisites 1–4. You also need a `DevopsProjectId` to file under and an `OwnerId` (assignee). See `references/work-item-creation.md`.
+
+---
+
+## Part 1 — Classify and explain each failure
+
+Determine the failure category, then for each failure extract and translate to plain language: offending file/class, method, line number, the rule or assertion violated, and a fix direction (without writing code). Group failures by category if more than one.
+
+| 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`) |
+| Timeout | Test exceeded execution time limit |
+| Compile error | Class failed to compile |
+
+**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>
+```
+
+Full category/pattern tables and Code Analyzer rule translations: `references/failure-categories.md` and `references/code-analyzer-violations.md`.
+
+**Empty / 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 or suggestions.
+
+---
+
+## Part 2 — Improvement suggestions
+
+Run this **after execution completes with failures**, not on static source. For each failed test, reason over the failure message (the primary signal) to identify what the test is not handling, then produce a specific, actionable suggestion and a **fix location** (Test vs Production code). The full failure-pattern → suggestion mapping is in `references/failure-categories.md`.
+
+```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
+
+Overall: <N> improvement(s) across <M> failed test(s).
+```
+
+Do not rewrite the test — only describe what needs to change and why. **Fix location: Production code** indicates a code defect exposed by a sound test (track separately, not a test-quality blocker). **Fix location: Test** indicates the test needs hardening (setup, assertions, edge cases).
+
+---
+
+## Part 3 — Create a fix work item (optional, on request only)
+
+Trigger only when the user wants to create a fix work item, log a remediation, or assign a failure to a developer. This is a **write** operation with a mandatory confirmation gate. Follow `references/work-item-creation.md` for inputs, the subject/assignee/project confirmation gate, the `sf data create record --sobject WorkItem` call, and error handling.
+
+> Use `WorkItem` (no namespace) — `DevopsWorkItem` is not a supported sObject in this org version.
+
+If no `DevopsProject` exists in the org, report that the work item cannot be created until a project is set up — do NOT fabricate a project or proceed.
+
+---
+
+## Related skills
+
+- **`dx-devops-test-suite-run`** — produces the failure payload (via its polling step) that feeds this skill.
+- **`dx-devops-test-suite-assignments-configure`** — assign/strengthen the suites whose tests are failing.
+- **`generating-apex` / `generating-apex-test`** — to actually write fix code or new test classes (out of scope here).

package/skills/dx-devops-test-failures-analyze/references/code-analyzer-violations.md

@@ -0,0 +1,26 @@
+# Code Analyzer Violations
+
+For each Code Analyzer violation, always include:
+
+- The rule name translated to plain English
+- The exact line number
+- The fix direction (without writing code)
+
+## Rule-name translations (examples)
+
+| Rule name | Plain-language meaning | Fix direction |
+|---|---|---|
+| `ApexCRUDViolation` | A SOQL query or DML was made without checking object-level permissions first | Add a `Schema.sObjectType.<Object>.isAccessible()` (or `isCreateable`/`isUpdateable`) check before the operation |
+| `ApexSharingViolations` | A class that performs data access does not declare sharing enforcement | Add `with sharing` (or an explicit `without sharing` with justification) to the class declaration |
+| `ApexDangerousMethods` | A dangerous or disallowed method was used | Replace with the safe, supported alternative |
+| `EmptyCatchBlock` | An exception is being swallowed silently | Log or handle the exception rather than leaving the catch block empty |
+
+When a rule isn't in this table, translate it from its name and message into a plain-language description of what was violated, then give the fix direction.
+
+## 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.
+
+## Fix location for violations
+
+Code Analyzer violations almost always indicate a **production-code** fix — the static-analysis rule is flagging the code under test, not the test itself. Flag these as **Fix location: Production code** and track them separately from test-quality issues.

package/skills/dx-devops-test-failures-analyze/references/failure-categories.md

@@ -0,0 +1,85 @@
+# Failure Categories & Improvement Mapping
+
+## Inputs required per failed test
+
+- Test method name
+- Failure message (the assertion error or exception text)
+- Failure category (assertion failure, unhandled exception, timeout, compile error)
+
+## Category table
+
+| 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 |
+
+## Per-failure extraction (Part 1)
+
+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)
+
+Group failures by category if more than one.
+
+## Failure-pattern → improvement suggestion (Part 2)
+
+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 permissions — run as a user with the 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 production code, not the test |
+
+## Producing 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 **production code** (test is correct, code under test is broken)
+
+Do not rewrite the test — only describe what needs to change and why.
+
+## Test fix vs. production-code fix
+
+- **Fix location: Production code** — a code defect exposed by a sound test. Should NOT block suite promotion on test-quality grounds; track separately as a production defect.
+- **Fix location: Test** — the test needs hardening: missing setup, wrong assertions, inadequate coverage of edge cases (null inputs, bulk record volumes, mixed permission contexts, governor-limit boundaries).
+
+## Output formats
+
+**Part 1 — failure summary:**
+
+```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>
+```
+
+**Part 2 — improvement suggestions:**
+
+```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
+
+Overall: <N> improvement(s) across <M> failed test(s).
+```

package/skills/{checking-devops-prerequisites/SKILL.md → dx-devops-test-failures-analyze/references/prerequisite-checks.md}

@@ -1,22 +1,16 @@
----
-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
+# Prerequisite Checks — Shared DevOps Center Gate
 
-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.
+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`.
 
-## How other skills use this
+**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.
 
-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.
+## 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.
@@ -94,7 +88,7 @@ sf data query \
 
 ## Prerequisite 5 — Pipeline stage identified (conditional)
 
-Run **only** when the calling skill operates on a specific stage.
+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:
 
@@ -115,27 +109,4 @@ sf data query \
 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 |
+- **Deferred:** not required until the operation needs it

package/skills/{creating-fix-work-item/SKILL.md → dx-devops-test-failures-analyze/references/work-item-creation.md}

@@ -1,14 +1,10 @@
----
-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 platform-apex-generate)."
-metadata:
-  version: "1.0"
-  minApiVersion: "67.0"
----
+# Part 3 — Create a Fix Work Item
+
+Creates a DevOps Center `WorkItem` to track a fix for a test failure or Code Analyzer violation. This is an **optional write**, triggered only when the user asks to create a fix work item, log a remediation, or assign a failure to a developer.
 
 ## 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.
+Run Prerequisites 1–4 (`references/prerequisite-checks.md`). You need `doce-org-alias`, a `DevopsProjectId` to file under, and an `OwnerId` (assignee). If no `DevopsProject` exists, surface that the work item cannot be created until a project exists — do NOT fabricate a project or work item.
 
 ## Inputs required before creating
 
@@ -16,7 +12,7 @@ Load `checking-devops-prerequisites` first — Prerequisites 1–4. You need `do
 |---|---|
 | `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. |
+| `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. Default to the requesting user when no assignee is specified; ask only if the username is unknown and no default applies. |
 | `doce-org-alias` | Established in Prerequisites |
 
 ## Confirmation gate
@@ -46,7 +42,7 @@ sf data create record \
 
 ## On success
 
-Parse the returned `id` from the result and confirm:
+Parse the returned `id` and confirm:
 
 > "Fix work item created (`<id>`): `<subject>`. Assigned to `<assigneeName>` in the `<projectName>` project."
 
@@ -61,6 +57,6 @@ Never expose raw API error messages. Map errors to plain-language responses:
 | `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
+## No-project case
 
-- `analyzing-test-failures` — provides the failure analysis and improvement suggestions that motivate creating a fix work item
+If the `DevopsProject` query returns 0 records, report clearly that no DevOps Center project exists and the work item cannot be created until one is set up. Do NOT fabricate a project name/ID, do NOT proceed to the confirmation gate or the create command.