/dx-devops-conflict-resolve

name: dx-devops-conflict-resolve
description: "Use this skill to diagnose and resolve what blocks a DevOps Center promotion of a work item's feature branch: Git merge conflicts and deployment failures. DevOps Center is Git-backed, so overlapping metadata changes surface as merge conflicts against the target stage branch, resolved with git (detect, resolve markers, commit, push). Deploy failures often cite a missing dependency a full promotion can fix when the component already exists on the branch. TRIGGER when the user wants to check a work item for conflicts before promoting, resolve merge conflicts or leftover conflict markers in metadata files (.xml, .object-meta.xml, .cls), reconcile a feature branch with its target stage branch, or diagnose why a DevOps Center promotion or deployment failed and whether a full promotion or a missing-dependency fix will resolve it. DO NOT TRIGGER for running the promotion itself (use dx-devops-promote), creating or updating work items (use dx-devops-work-item-manage), or deploying metadata directly to an org."
metadata:
  version: "1.0"
  domains: ["Developer Experience"]
  minApiVersion: "58.0"
  relatedSkills:
    - "dx-devops-promote"
    - "dx-devops-work-item-manage"
  cliTools:
    - tool: ["git"]
      semver: ">=2.23"
    - tool: ["jq"]
      semver: ">=1.6"
    - tool: ["sf"]
      semver: ">=2.0.0"
  accessCheck: "(OrgPreferences.ALMDevopsCorePref) && (UserPermissions.UserHasDevOpsCore)"

DevOps Center Conflict & Deploy-Failure Resolution

Diagnoses and resolves what blocks a DevOps Center promotion of a work item's feature branch. DevOps Center is Git-backed: each work item is a feature branch and each pipeline stage has a target branch. A promotion can fail two ways — a **Git merge conflict** (two work items changed the same metadata) or a **deployment failure** (the deploy itself errors, often on a **missing dependency**). There is no `sf devops conflict` CLI command; both cases are diagnosed and resolved with standard **git** against the connected repository. This skill runs in a local clone of that repo.

Scope

• **In scope**: (a) Detect merge conflicts between a work item's feature branch and the target stage branch (non-destructively), resolve conflicted files (choose a side or manually merge conflict markers), commit, and push the feature branch DevOps Center tracks; (b) Diagnose a promotion **deploy failure** — classify it as a merge conflict vs. a deploy error, parse a missing dependency, and determine whether a **full promotion** can fix it (the component exists on the feature branch) or the component must be added first
• **Out of scope**: Running the promotion, full promotion, or combine (use `dx-devops-promote`), creating/updating work items or their status (use `dx-devops-work-item-manage`), deploying metadata directly to an org, pipeline or project setup (separate skills)

---

Required Inputs

Gather or infer before proceeding:

• **Local clone** of the DevOps Center connected Git repository (the agent runs git commands here). Confirm the working tree is clean before starting.
• **Feature branch name** — the branch backing the work item. If the user gives a work item ID/subject instead, resolve it to its branch (see the Reference File Index for the `sf devops work-item` lookup).
• **Target stage branch name** — the branch of the pipeline stage the work item promotes into (e.g. the integration/UAT branch).
• **Remote name** — defaults to `origin`.
• **Deploy error text** (deploy-failure track only) — the promotion's error output/summary. Needed to classify the failure and parse a missing dependency. Capture it to a file or pipe it into the diagnosis script.

Defaults unless specified:

• Remote: `origin`
• Merge direction: merge the **target stage branch into the feature branch** (reconcile the work item with where it is going)

If the user names both branches ("resolve conflicts on `feature/WI-101` against `uat`"), proceed. If they give a work item, resolve its branch first.

---

Workflow

DevOps Center promotion blockers are Git-level. Detection and diagnosis are deterministic (scripts); resolving each conflicted file requires judgment (prose). Never resolve without first detecting on a clean tree.

**Route first.** Pick the track from the user's situation:

• **Merge conflict track** — the user wants a pre-promotion conflict check, or a promotion failed and the cause is (or is suspected to be) a merge conflict → Phases 1–4 below.
• **Deploy-failure track** — a promotion's *deploy* failed with an error message and the user wants to know why and how to fix it → Phase D below. If Phase D classifies the failure as a merge conflict, fall through to the merge-conflict track.

Phase 1 — Authenticate and orient

1. **Confirm the local repo and clean tree.** Run in the repo clone:

   git rev-parse --is-inside-work-tree && git status --porcelain

• If `git status --porcelain` prints anything, the tree is dirty — instruct the user to commit or stash first. A trial merge on a dirty tree is unsafe.

2. **Resolve a work item to its branch (only if the user gave a work item, not a branch).** Verify org auth with `sf org display --json`; if it fails, tell the user to run `sf org login web --set-default --alias <alias>`. Then look up the branch — see `references/git-conflict-resolution.md`.

Phase 2 — Detect (non-destructive)

3. **Run the detection script.** It fetches, trial-merges the target branch into the feature branch without committing, lists conflicted files, and aborts the trial so the tree is left untouched:

   scripts/detect-conflicts.sh <feature-branch> <target-branch> [remote]

• Exit `0` = clean merge (no conflicts) → report "safe to promote" and STOP.
• Exit `2` = conflicts found → the script prints the conflicting file list; proceed to Phase 3.
• Exit `1` = error (dirty tree, unknown branch, fetch failure) → report the error and STOP; do not treat an