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 — 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
is consulted. For a planned upgrade or downgrade, it reports the gap
and then STOPS for explicit user confirmation. For a failed or partial
upgrade, it enters [`TASKS.md ## debug`](TASKS.md#debug) first to
capture and stabilize the current state; it never uses another
upgrade command as the first recovery action, retries the move, or
issues a new upgrade command without explicit confirmation.

## 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 |

First classify the request. A **planned move** (including a requested
rollback) follows detect → report → ASK. A **failed, partial, or
accidentally drifted move** is already a diagnosis/recovery request:
load this skill, capture the current four-source state, and enter
`TASKS.md ## debug`; do not ask for permission to perform an upgrade
that has already failed, and do not issue another upgrade command as
the first recovery action.

For a planned move, the agent MUST:

1. Route planned-upgrade version detection to
   [`doca-version ## configure`](../doca-version/TASKS.md#configure).
   For failed or partial upgrades, start with
   [`doca-version ## debug`](../doca-version/TASKS.md#debug) and
   [`TASKS.md ## debug`](TASKS.md#debug). Do NOT restate the
   four-source detection chain here; this skill consumes the detected
   state and four-way match status.
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.

For a failed/partial move, the agent MUST instead classify the
captured state against
[`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy),
delegate the single documented corrective action, and re-enter the
recovery ladder. Any unsupported `installed → target` jump fails
closed: do not improvise intermediate releases or commands; require
an upgrade path explicitly documented by the Compatibility Policy or
release notes.

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.