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

The single most important rule this skill exists to enforce: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 — and 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. The skill's contract is unconditional: it reports the gap and then STOPS for explicit user confirmation; it never issues an upgrade command on the user's behalf without that confirmation.

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

When any cell above fires, the agent MUST:

1. Route version detection to doca-version ## configure — do NOT restate the four-source detection chain here; this skill consumes the detected version and the 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), 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. 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), 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

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