Doca Upgrade

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 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 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, never

redefined here. Version detection itself is owned by

doca-version; 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, which routes the

detection to doca-version and the

*what is current* lookup to

doca-public-knowledge-map.

• **"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

plus the ask-before-acting step in

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

and the failed-upgrade diagnosis in

TASKS.md ## debug, which re-routes the

detection to doca-version ## 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

plus the recovery ladder in 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 via

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,

which routes the user to the public release notes via

doca-public-knowledge-map

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

• Route planned-upgrade version detection to

doca-version ## configure.

For failed or partial upgrades, start with

doca-version ## debug and

TASKS.md ## debug. Do NOT restate the

four-source detection chain here; this skill consumes the detected

state and four-way match status.

• 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),

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

command until the user explicitly says yes.

• Route every hardware / firmware / reboot step to

doca-hardware-safety. 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,

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), for the version-detection

chain in isolation (use doca-version),

or for general orientation (use

doca-public-knowledge-map).

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

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

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

• **For the upgrade-mode taxonomy, the never-auto rule, the

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

the safety overlay, see CAPABILITIES.md.**

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

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

failed-upgrade diagnosis — see TASKS.md.**

Related skills

• doca-version — 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 — 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 — 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 —

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

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 —

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.