/doca-upgrade

license: Apache-2.0
name: doca-upgrade
description: >
  Use this skill when the user is contemplating a DOCA upgrade or
  downgrade — moving a host to a newer DOCA release, refreshing the
  BlueField BFB, bumping the NGC DOCA container tag, or rolling back.
  The discipline is detect → report → ASK → only-then guided upgrade:
  detect what is installed, discover what newer release exists, report
  the gap, then STOP and ask for explicit confirmation — never upgrade
  automatically. Trigger even without the word "upgrade": "is there a
  newer DOCA", "should I move to the next release", "I want the latest
  features", "my component is being deprecated, what now", or "roll me
  back". Route elsewhere for version detection (doca-version),
  first-time install (doca-setup), any hardware/firmware/reboot step
  (doca-hardware-safety), and public-docs / sunset routing
  (doca-public-knowledge-map).
metadata:
  kind: library
compatibility: >
  No DOCA install required to read this skill (it is a cross-cutting
  overlay loaded against any DOCA artifact skill); the detection,
  gap-report, and guided-upgrade steps within DO require a live DOCA
  install at /opt/mellanox/doca, and the hardware / firmware / reboot
  steps require a BlueField DPU or ConnectX NIC plus out-of-band
  console reachability as gated by doca-hardware-safety.

DOCA upgrade

**Where to start:** This skill is the bundle's single source of truth for the discipline that wraps a DOCA *upgrade or downgrade*. Open [`TASKS.md`](TASKS.md) when the user wants to *do* something with an upgrade (detect the gap, ask for confirmation, walk the guided upgrade, verify it, or diagnose a failed one); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what does an upgrade even cover* (the host apt-upgrade vs BFB reflash vs container-tag bump vs downgrade/rollback modes, the never-auto rule, the confirmation gate, the sunset-awareness concern, the error taxonomy, and the upgrade-specific safety overlay).

**For a planned move, the single most important rule this skill exists to enforce is detect → report → ASK → only-then guided upgrade. Never upgrade automatically.** The skill detects the installed DOCA env and what newer release is available, reports the gap clearly, then STOPS and asks the user for explicit confirmation. Only on an explicit "yes" does it walk a guided upgrade. A failed or partial move instead enters the recovery ladder without presenting a new target move. In both paths every hardware / firmware / reboot step is delegated to [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md), never redefined here. Version detection itself is owned by [`doca-version`](../doca-version/SKILL.md); this skill routes there and does not restate the detection chain.

Example questions this skill answers well

The CLASSES of upgrade questions this skill is built to answer, each with one worked example. The agent should treat the *class* as the load-bearing piece — the worked example is a single instance.

• **"Is there a newer DOCA than what I have, and how far behind am

I?"** — worked example: *"`pkg-config --modversion doca-common` says 3.1.0; what's current and what does moving cost me?"*. Answered by the detect-and-report-the-gap workflow in [`TASKS.md ## configure`](TASKS.md#configure), which routes the detection to [`doca-version`](../doca-version/SKILL.md) and the *what is current* lookup to [`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md).

• **"Should I just run `apt upgrade` to move to the next DOCA

release?"** — worked example: *"I want the newest Flow features; can I upgrade in place right now?"*. Answered by the never-auto rule and the confirmation gate in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy) plus the ask-before-acting step in [`TASKS.md ## run`](TASKS.md#run) — the agent reports the gap and STOPS for explicit confirmation before any upgrade command runs.

• **"My upgrade left the host on a different release than the

BlueField — what happened?"** — worked example: *"after the upgrade `pkg-config` says 3.3.0 but `bfver` still says 3.1.0"*. Answered by the host/BFB-skew row in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy) and the failed-upgrade diagnosis in [`TASKS.md ## debug`](TASKS.md#debug), which re-routes the detection to [`doca-version ## test`](../doca-version/TASKS.md#test).

• **"The upgrade aborted half-way and now `dpkg` is wedged — how do

I recover?"** — worked example: *"`apt upgrade` was interrupted; `dpkg` reports an interrupted transaction"*. Answered by the partial-upgrade and aborted-transaction rows in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy) plus the recovery ladder in [`TASKS.md ## debug`](TASKS.md#debug).

• **"The upgrade needs me to reflash the BFB / flip BlueField mode /

reboot — is that safe?"** — worked example: *"the target release requires a new BFB; can I reflash now?"*. Answered by routing every hardware / firmware / reboot step to [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md) via [`TASKS.md ## run`](TASKS.md#run); this skill never redefines the reflash, mode-flip, or cold-power-cycle discipline.

• **"My installed component is being sunset — should I keep building

on it or move?"** — worked example: *"I rely on DOCA App Shield / the DOCA Flow Inspector service; are they on a deprecation track?"*. Answered by the sunset / deprecation awareness concern in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes), which routes the user to the public release notes via [`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md) to confirm lifecycle status rather than recommending continued investment in a component that may be sunsetting.

When to load this skill

Load this skill whenever an upgrade or downgrade of DOCA is the load-bearing concern —