git:20260717.f64fa0e to git:20260727.a5736e4

---

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).

[`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 — the user is asking whether a newer release

exists, whether to move to it, how to move safely, or how to recover

a move that went wrong. The decision must be made **before** the

agent composes its first sentence; the activation checklist below is

mirrored here so the activation rule is at hand whenever this skill

## Agent activation checklist — load this skill at the START of the answer when any cell below is true

| Trigger class | Concrete prompt-side signals (any one fires the overlay) |

| --- | --- |

| Upgrade / downgrade intent | *"is there a newer DOCA"*, *"should I move to the next release"*, *"upgrade me to the latest"*, *"roll me back to the previous DOCA"*, *"downgrade to 3.1 for a bug repro"* |

| Accidental / drifted upgrade | *"`apt upgrade` pulled a newer DOCA point release and broke my build"*, *"my host and BlueField are on different releases now"*, *"the source channel is `latest` and I didn't mean to move" * |

| Failed / partial upgrade | *"the upgrade aborted half-way"*, *"`dpkg` is wedged after an interrupted transaction"*, *"upgrade finished but the four-way match no longer holds"* |

| Container tag bump | the user wants to move an NGC DOCA container deployment from one tag to a newer one, or asks whether bumping the tag is an upgrade |

| Sunset / deprecation awareness | the user asks whether the component they depend on is deprecated, being sunset, or worth continued investment |

2. **Report the gap and STOP for explicit confirmation.** Present

the installed release, the available target release, and what

moving costs (per

[`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility)),

then ask the user to confirm. Do NOT proceed to any upgrade

command until the user explicitly says yes.

3. Route every hardware / firmware / reboot step to

[`doca-hardware-safety`](../doca-hardware-safety/SKILL.md). This

skill names *when* such a step is part of the upgrade; that skill

names *how* it is applied safely.

Do **not** load this skill for first-time install (use

[`doca-setup`](../doca-setup/SKILL.md)), for the version-detection

chain in isolation (use [`doca-version`](../doca-version/SKILL.md)),

or for general orientation (use

[`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md)).

## What this skill provides

This is a **thin loader**. The body keeps only the orientation

needed to pick the right next file. The substantive upgrade material

lives in two companion files:

- `CAPABILITIES.md` — the upgrade surface: the upgrade-mode taxonomy

(host apt upgrade vs BFB reflash vs container-tag bump vs

downgrade/rollback), the never-auto rule and the confirmation

gate, the sunset / deprecation-awareness concern, the

version-compatibility overlay that redirects to `doca-version`,

the error taxonomy (partial upgrade, apt-source drift, host/BFB

skew, aborted transaction / `dpkg` interrupted), the observability

surface (which commands prove the upgrade did or did not happen),

and the upgrade-specific safety overlay on top of

`doca-hardware-safety`.

- `TASKS.md` — step-by-step workflows for the in-scope verbs:

`configure` (detect + discover target + apt-source precheck),

`build` and `modify` (routing stubs — the version-pin change is

owned elsewhere), `run` (the confirmation-gated guided upgrade),

`test` (post-upgrade four-way verification), `debug` (diagnose a

failed / partial upgrade), plus a `Deferred task verbs` block.

## Loading order

1. Read this `SKILL.md` first to confirm the user's question is in

scope (an upgrade / downgrade is being contemplated or recovered).

2. **For the upgrade-mode taxonomy, the never-auto rule, the

sunset-awareness concern, the error taxonomy, observability, and

the safety overlay, see [CAPABILITIES.md](CAPABILITIES.md).**

3. **For step-by-step workflows — detect-and-report, the

confirmation-gated guided upgrade, post-upgrade verification, and

failed-upgrade diagnosis — see [TASKS.md](TASKS.md).**

## Related skills

- [`doca-version`](../doca-version/SKILL.md) — owns the four-source

detection chain and the four-way match rule. This skill's detect

step routes there and does not redefine version detection; the

gap report consumes the detected version.

- [`doca-setup`](../doca-setup/SKILL.md) — owns first-time install,

install verification, and the apt-source path. This skill's

apt-source consistency precheck cross-links there before any

`apt`-shaped upgrade is contemplated.

- [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md) — owns

every hardware / firmware / reboot step (mlxconfig, BFB reflash,

BlueField mode flip, cold power cycle). This skill's `## Safety

policy` overlays that meta-policy and adds only the

upgrade-specific surface (confirmation gate, rollback-first,

maintenance window).

- [`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md) —

the routing table to public DOCA docs, including the release notes

and the Compatibility Policy. This skill routes *what is the

current release* and *is this component sunsetting* there; it does

not duplicate the routing.

- [`doca-debug`](../doca-debug/SKILL.md) — the cross-cutting debug

ladder. A failed upgrade whose residual symptom lives at a

software layer hands off there once the upgrade state is known.

- [`doca-programming-guide`](../doca-programming-guide/SKILL.md) —

the build pattern a consumer rebuilds against after an upgrade.

This skill surfaces *that* a rebuild may be needed; the build

mechanics live there.

- [`doca-structured-tools-contract`](../doca-structured-tools-contract/SKILL.md) —

the JSON schemas the agent prefers when present; the upgrade

detect step reuses the same `doca-env` one-shot the version skill

uses, when the host has it.