afv-library/skills/creating-fix-work-item/SKILL.md

name	description	metadata
creating-fix-work-item	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).	version minApiVersion 1.0 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

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