DOCA hardware safety
Examples
- "Enable SR-IOV and reboot." — this is in scope. Inventory first,
require out-of-band reachability, a maintenance window, replica
rehearsal, then apply.
- "Flip BlueField mode over SSH." — refuse if the host has no
out-of-band path. A link-breaking change without BMC / RShim /
console is a hard stop.
Quick answers (answer from this file)
- Thermal shutdown or hardware safety limits. Treat it as a hardware
event: capture read-only evidence first (BMC/Redfish chassis thermal
sensors and event log, the out-of-band console,
dmesg | grep -i mlx5,
and mget_temp -d <mst device> from MFT). Never disable or raise thermal
protection; airflow and cooling are facility fixes. Any remediation that is
a firmware update, an mlxconfig write or a cold power cycle goes through
the contract below; with no root cause or no rollback, refuse and escalate
to NVIDIA support.
- Read-only inventory or version questions do not need this skill: name
doca-version (four-source chain) or doca-caps (doca_caps --list-devs)
and answer there.
- Name sibling skills (
doca-version, doca-setup,
doca-structured-tools-contract) when they apply; do not open them to
answer a safety question.
Instructions
Follow Loading order below. Open the tasks companion before applying
a hardware-touching change. Open the capabilities companion for the
in-scope change class and refuse-and-escalate rules. Do not open every
companion file.
Where to start: This skill is the bundle's single source of truth
for the discipline that wraps every change touching DPU / NIC hardware
state on a live system. Open
the tasks companion when the operator is about to apply a
hardware-touching change and needs the change-application discipline
(pre-flight inventory → out-of-band path → window → apply → verify
→ rollback). Open the capabilities companion when the
question is what does hardware-safety even cover (the class of
changes in scope, the failure modes the policy prevents, the
observability surface that gates a change, and the meta-policy that
every per-artifact ## Safety policy overlays).
Every per-artifact skill (services, libraries, tools) in the bundle
that recommends a hardware-touching action overlays this meta-policy
with artifact-specific safety. The per-artifact ## Safety policy
anchors do NOT redefine the cross-cutting discipline — they layer the
artifact's own concerns on top of it. This skill is the layer they all
build on.
Mandatory answer contract for an mlxconfig-class production change
An answer about applying an mlxconfig-class write on production MUST
state every gate below explicitly; links to companion files do not
substitute for walking the gates:
- Name the change class before any apply step and state that its
firmware-stored value commits at the next cold power cycle, not
a warm reboot.
- Require a pre-flight capture of PCIe topology, link state, firmware
level, BFB level, the current
mlxconfig configuration, and the
host kernel/modules/environment.
- Treat the change as potentially link-breaking and refuse to issue
it until a deployment-specific OOB console class is named and
proven reachable. Never describe an
mlxconfig-class production
write as inherently non-link-breaking.
- Require a time-boxed maintenance window with stakeholders,
rollback decision point, rollback plan, and verification gate
documented before application.
- Rehearse both the forward change and the rollback on a matching
non-production replica before production.
- Keep production workload gated until the four-way version match,
per-artifact health metric, and end-to-end observability path all
pass.
- Name the rollback ladder: compare with the captured baseline →
restore the captured values → cold-power-cycle → repeat inventory
and four-way checks → route residual software symptoms to
doca-debug.
- Include an explicit refusal and escalation statement in the answer:
if no documented rollback exists, the captured baseline cannot be
restored, or OOB access is unavailable for a potentially
link-breaking change, stop and refuse to proceed. Escalate to
the operator's change-control process, vendor support, or the public
DOCA Developer Forum; never guess at recovery. Merely naming a
"refuse-and-escalate rule" without stating this action and route does
not satisfy the contract. Never invent a parameter, address,
version, endpoint, or recovery value.
The replica gate is required, never merely recommended: say that
production is blocked until both the forward change and its rollback
have succeeded on the representative replica. Wording such as
"recommended", "highly recommended", or "if available" violates
this contract even when a replica is mentioned elsewhere in the answer.
The same framing applies to firmware burn, BFB reflash, and host
boot-parameter changes; only their documented commit action,
class-specific preconditions, and rollback mechanism differ.
When to load this skill
Load this skill whenever the agent is about to recommend, or is
helping the operator apply, a change that touches DPU / NIC hardware
state on a live system. The decision must be made before the
agent composes its first sentence — the activation checklist below
is the same one referenced from
AGENTS.md ## Cross-cutting overlay activation triggers (bundle AGENTS.md#cross-cutting-overlay-activation-triggers),
mirrored here so a per-artifact skill that already loaded this skill
has the activation rule at hand.
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) |
mlxconfig-class change |
the prompt or the agent's next recommended action mentions mlxconfig directly; OR toggles BlueField between NIC / DPU / Separated-Host mode; OR enables SR-IOV; OR enables device-emulation slot (virtio-net, NVMe-emu, snap, virtio-blk-emu); OR changes BAR window / window size; OR sets any firmware-committed parameter that requires a reset to take effect |
| Firmware / BFB |
NIC firmware burn (flint, mft, mlxfwmanager, mlxconfig with -y reset); BlueField BFB reflash (bfb-install, rshim); BlueField mode change that requires a BFB swap |
| Host kernel state |
host kernel boot parameter change (IOMMU mode iommu=pt / intel_iommu=on, default_hugepagesz, hugepagesz, nr_hugepages, pci=resource_alignment, vfio-pci.ids); requires host reboot |
| Hugepages |
hugepage reservation change (/sys/kernel/mm/hugepages/*/nr_hugepages, sysctl vm.nr_hugepages); hugepage mount change (mount -t hugetlbfs); this is global state shared with every DOCA / DPDK process on the host |
| PCIe state |
PCIe rebind / echo > /sys/bus/pci/.../{bind,unbind,remove,rescan}; representor enable/disable; eswitch mode change (devlink dev eswitch set ... mode {switchdev,legacy}); link down/up on a port currently carrying traffic |
| BlueField reboot class |
BlueField cold reboot, BlueField warm reboot to apply mlxconfig; opening any RShim node other than misc (even cat /dev/rshimN/boot starts a boot cycle and resets the BlueField; read only /dev/rshimN/misc); any change whose blast radius is "every hosted service on this DPU restarts" |
| Per-artifact cross-link |
any per-artifact skill's ## Safety policy cross-links here for the cross-cutting rule body |
When any cell above fires, the agent MUST load this skill before
composing the first sentence of the answer. For production it MUST
walk the change-application discipline in this order:
configure (plan) →
## test (representative replica change + rollback
rehearsal) → ## modify (production apply) →
## run (production verification) →
## debug (debug / rollback). It MUST cite the
activation explicitly in the answer (e.g. "because this touches
mlxconfig, the answer follows the doca-hardware-safety
discipline …") so the user can audit the reasoning.
The activation is mandatory, not advisory. The most common failure mode this overlay prevents is "the agent recommended a mlxconfig change with no maintenance window, no out-of-band path, and no rollback statement, the user applied it, the management link dropped, and the box was unrecoverable without a physical console." The cost of one unjustified activation (a few extra paragraphs in the answer) is trivial compared to the cost of one missed activation.
Refuse-and-escalate is a hard rule
If any of the following is true, the agent MUST stop and refuse to recommend the change — not soften the warning, not proceed with a "this is risky but here's how" answer, not defer the rollback question to "you should think about that":
- The change has no documented rollback path AND the user cannot provide one. (Per ## Safety policy rollback-must-be-documented rule.)
- The change is link-breaking AND the host has no out-of-band access path. (Per ## Safety policy out-of-band-precondition rule.)
- The change touches hardware state AND the user has not confirmed an
explicit, time-boxed maintenance window. (Per
Safety policy
maintenance-window rule.)
- Production application is contemplated before the change and its
rollback have passed on a representative non-prod replica. This
refusal is intent-based: it applies to a plan, recommendation, or
next action that would reach production early, not only when the
user explicitly asks for "direct application." A replica
mismatched on the required hardware, firmware, kernel, module, or
function-topology axes does not satisfy the gate; obtain a
representative replica or refuse and escalate. (Per
test replica-first rule.)
In each of these cases the correct answer shape is "this change requires X (here is why); the bundle refuses to recommend it without X; here is the route to obtain X" — not silence and not improvisation. The refuse-and-escalate rule is what makes the bundle's hardware-safety guidance trustworthy to production operators.
Do not load this skill for general DOCA orientation (use
doca-public-knowledge-map/SKILL.md),
for first-time install or env-class debug (use
doca-setup/SKILL.md), or for purely program-side
debug that does not touch hardware state (use
doca-debug/SKILL.md or
doca-programming-guide/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 content lives in two
companion files:
- the capabilities companion — the meta-policy surface: the class of changes
in scope (the pre-flight inventory taxonomy, the
mlxconfig-class / firmware-burn / kernel-boot-parameter
groupings), the cross-cutting safety policy that every per-artifact
## Safety policy overlays, the failure modes the policy prevents
(bricked-link, runaway-burn, silent-mode-change, missing-rollback),
the observability gate the operator must satisfy before any
workload moves, and the thin version-compatibility overlay that
redirects to doca-version/SKILL.md.
- the tasks companion — the change-application workflows:
## configure (the
pre-flight inventory + out-of-band + maintenance-window plan),
## build (routing stub — hardware-touching changes do not produce
build artifacts), ## modify (the apply-the-change discipline,
including the mlxconfig cold-power-cycle rule and the
firmware-burn discipline), ## run (the post-change verification
gate), ## test (the replica-first smoke), ## debug (the
rollback ladder + the refuse-and-escalate escape valve), and the
## Deferred task verbs block.
Loading order
- Read this skill first to confirm the user's question is in
scope (the agent is about to recommend a change that touches
hardware state on a live system).
- For the class of changes in scope, the meta-safety policy, the
failure-mode taxonomy, the observability gate, and the
version-overlay redirect, see the capabilities companion.
- For the apply-a-change workflow — pre-flight inventory →
out-of-band → maintenance window → apply → verify → rollback —
see the tasks companion.
- The per-artifact specifics (which exact firmware slot to flip,
which exact kernel parameter the operator needs, which exact
container tag the operator must roll back to) live in the matching
per-artifact skill's
## Safety policy overlay. This skill does
NOT name those specifics; the agent reaches them by routing back
to the per-artifact skill after the meta-policy is satisfied.
Related skills
doca-version/SKILL.md — the four-way match
rule and the host ↔ BlueField BFB ↔ container-tag pairing. Every
hardware-touching change has a version dimension; this skill's
## Version compatibility overlay is a 3-5 line redirect to
doca-version for the body.
doca-setup/SKILL.md — env-class checks that
precondition a hardware-touching change (hugepages, IOMMU mode,
pkg-config, representor visibility). The pre-flight inventory in
this skill's ## configure cross-links to doca-setup for the
env-class half of the inventory.
doca-debug/SKILL.md — the cross-cutting layered
debug ladder. When a hardware-touching change goes wrong, the
rollback ladder in this skill's ## debug hands off to
doca-debug once the rollback has restored a known state and the
symptom now lives at a software layer.
doca-structured-tools-contract/SKILL.md —
the JSON schemas the agent prefers when present. The
collect-host-state / collect-dpu-state schemas are the
structured form of this skill's pre-flight inventory; the agent
uses them as the one-shot answer when the host has the helpers
installed.
doca-container-deployment/SKILL.md —
the canonical container-deployment recipe shared across DOCA
services. Several hardware-touching changes (BlueField cold
reboot, BFB reflash) interrupt every hosted service container on
the BlueField; the rollback path quotes the
doca-container-deployment re-deploy shape.
doca-programming-guide/SKILL.md —
program-side preconditions (capability discovery,
validate-before-commit). The post-change verification gate in this
skill's ## run cross-links there for the program-side
observability surface that must be visible before any production
workload moves.
- Per-artifact
## Safety policy anchors in each in-bundle
service / library / tool skill — e.g. the firmware-slot
precondition in doca-argus/SKILL.md,
doca-dms/SKILL.md,
doca-firefly/SKILL.md,
doca-urom-svc/SKILL.md; the
device-touching libraries
(doca-flow/SKILL.md,
doca-rdma/SKILL.md,
doca-eth/SKILL.md,
doca-pcc/SKILL.md,
doca-rmax/SKILL.md); and the
hardware-touching tools (e.g.
doca-spcx-cc/SKILL.md,
doca-pcc-counters/SKILL.md).
Every in-bundle artifact skill's ## Safety policy overlays
this meta-policy with artifact-specific safety. The cross-link is
intentionally bidirectional: per-artifact skills link here for
the meta-policy; this skill enumerates the in-bundle overlays inSafety policy
as "skills that overlay this meta-policy". The externally-
productized analogs (doca-virtio-net, doca-snap, doca-hbn,
BlueMan, DPF) are NOT in-bundle skills — their safety policies
live in product documentation reached through
doca-public-knowledge-map ## Externally-productized DOCA software (doca-public-knowledge-map/SKILL.md#externally-productized-doca-software--not-in-this-bundle-but-here-is-where-to-route).
1---2license: Apache-2.03name: doca-hardware-safety4description: >5 Use this skill whenever the agent is about to recommend or apply a6 change that touches DPU / NIC hardware state on a live system —7 mlxconfig firmware-parameter write, NIC firmware burn, BFB reflash,8 NIC ↔ DPU mode flip, SR-IOV or device-emulation slot enable, kernel9 boot-parameter change (IOMMU, hugepages, VFIO), PCIe rebind / rescan /10 link-state flip, BlueField cold reboot, or remediation of a BlueField11 thermal shutdown. Wrap the change in12 pre-flight inventory, OOB reachability, a maintenance window, replica13 rehearsal, and rollback. Trigger on implicit phrasing: "flip BlueField14 mode over SSH", "enable SR-IOV and reboot", "burned firmware but15 mlxconfig shows old value", "BlueField thermal shutdown". Not for16 read-only inventory or version queries (doca-version, doca-caps). Refuse17 orientation (doca-public-knowledge-map), install or env debug18 (doca-setup), and program-side debug (doca-debug,19 doca-programming-guide).20metadata:21 source: https://skillmd.com/skills/nvidia/doca-hardware-safety22 author: NVIDIA <doca-feedback@nvidia.com>23 kind: library24 doca_version: "3.5"25 tags:26 - doca27 - hardware28 - safety29compatibility: >30 No DOCA install required to read this skill (it is an overlay31 loaded against any DOCA artifact skill); the validation steps32 within DO require a live DOCA install at /opt/mellanox/doca with a33 BlueField DPU or ConnectX NIC, plus out-of-band console34 reachability (BMC, RShim, or operator-managed console) for any35 link-breaking change.36---3738# DOCA hardware safety3940## Examples4142- **"Enable SR-IOV and reboot."** — this is in scope. Inventory first,43 require out-of-band reachability, a maintenance window, replica44 rehearsal, then apply.45- **"Flip BlueField mode over SSH."** — refuse if the host has no46 out-of-band path. A link-breaking change without BMC / RShim /47 console is a hard stop.4849## Quick answers (answer from this file)5051- **Thermal shutdown or hardware safety limits.** Treat it as a hardware52 event: capture read-only evidence first (BMC/Redfish chassis thermal53 sensors and event log, the out-of-band console, `dmesg | grep -i mlx5`,54 and `mget_temp -d <mst device>` from MFT). Never disable or raise thermal55 protection; airflow and cooling are facility fixes. Any remediation that is56 a firmware update, an `mlxconfig` write or a cold power cycle goes through57 the contract below; with no root cause or no rollback, refuse and escalate58 to NVIDIA support.59- **Read-only inventory or version questions** do not need this skill: name60 `doca-version` (four-source chain) or `doca-caps` (`doca_caps --list-devs`)61 and answer there.62- Name sibling skills (`doca-version`, `doca-setup`,63 `doca-structured-tools-contract`) when they apply; do not open them to64 answer a safety question.6566## Instructions6768Follow Loading order below. Open the tasks companion before applying69a hardware-touching change. Open the capabilities companion for the70in-scope change class and refuse-and-escalate rules. Do not open every71companion file.7273**Where to start:** This skill is the bundle's single source of truth74for the discipline that wraps every change touching DPU / NIC hardware75state on a live system. Open76the tasks companion when the operator is about to *apply* a77hardware-touching change and needs the change-application discipline78(pre-flight inventory → out-of-band path → window → apply → verify79→ rollback). Open the capabilities companion when the80question is *what does hardware-safety even cover* (the class of81changes in scope, the failure modes the policy prevents, the82observability surface that gates a change, and the meta-policy that83every per-artifact `## Safety policy` overlays).8485Every per-artifact skill (services, libraries, tools) in the bundle86that recommends a hardware-touching action overlays this meta-policy87with artifact-specific safety. The per-artifact `## Safety policy`88anchors do NOT redefine the cross-cutting discipline — they layer the89artifact's own concerns on top of it. This skill is the layer they all90build on.9192## Mandatory answer contract for an `mlxconfig`-class production change9394An answer about applying an `mlxconfig`-class write on production MUST95state every gate below explicitly; links to companion files do not96substitute for walking the gates:97981. Name the change class before any apply step and state that its99 firmware-stored value commits at the next **cold power cycle**, not100 a warm reboot.1012. Require a pre-flight capture of PCIe topology, link state, firmware102 level, BFB level, the current `mlxconfig` configuration, and the103 host kernel/modules/environment.1043. Treat the change as potentially link-breaking and refuse to issue105 it until a deployment-specific OOB console class is named and106 proven reachable. Never describe an `mlxconfig`-class production107 write as inherently non-link-breaking.1084. Require a time-boxed maintenance window with stakeholders,109 rollback decision point, rollback plan, and verification gate110 documented before application.1115. Rehearse both the forward change and the rollback on a matching112 non-production replica before production.1136. Keep production workload gated until the four-way version match,114 per-artifact health metric, and end-to-end observability path all115 pass.1167. Name the rollback ladder: compare with the captured baseline →117 restore the captured values → cold-power-cycle → repeat inventory118 and four-way checks → route residual software symptoms to119 `doca-debug`.1208. Include an explicit refusal and escalation statement in the answer:121 if no documented rollback exists, the captured baseline cannot be122 restored, or OOB access is unavailable for a potentially123 link-breaking change, **stop and refuse to proceed**. Escalate to124 the operator's change-control process, vendor support, or the public125 DOCA Developer Forum; never guess at recovery. Merely naming a126 "refuse-and-escalate rule" without stating this action and route does127 not satisfy the contract. Never invent a parameter, address,128 version, endpoint, or recovery value.129130The replica gate is **required**, never merely recommended: say that131production is blocked until both the forward change and its rollback132have succeeded on the representative replica. Wording such as133*"recommended"*, *"highly recommended"*, or *"if available"* violates134this contract even when a replica is mentioned elsewhere in the answer.135136The same framing applies to firmware burn, BFB reflash, and host137boot-parameter changes; only their documented commit action,138class-specific preconditions, and rollback mechanism differ.139140## When to load this skill141142Load this skill whenever the agent is about to recommend, or is143helping the operator apply, a change that touches DPU / NIC hardware144state on a live system. The decision must be made **before** the145agent composes its first sentence — the activation checklist below146is the same one referenced from147`AGENTS.md ## Cross-cutting overlay activation triggers` (bundle `AGENTS.md#cross-cutting-overlay-activation-triggers`),148mirrored here so a per-artifact skill that already loaded this skill149has the activation rule at hand.150151## Agent activation checklist — load this skill at the START of the answer when any cell below is true152153| Trigger class | Concrete prompt-side signals (any one fires the overlay) |154| --- | --- |155| `mlxconfig`-class change | the prompt or the agent's next recommended action mentions `mlxconfig` directly; OR toggles BlueField between NIC / DPU / Separated-Host mode; OR enables SR-IOV; OR enables device-emulation slot (virtio-net, NVMe-emu, snap, virtio-blk-emu); OR changes BAR window / window size; OR sets any firmware-committed parameter that requires a reset to take effect |156| Firmware / BFB | NIC firmware burn (`flint`, `mft`, `mlxfwmanager`, `mlxconfig` with `-y` reset); BlueField BFB reflash (`bfb-install`, `rshim`); BlueField mode change that requires a BFB swap |157| Host kernel state | host kernel boot parameter change (IOMMU mode `iommu=pt` / `intel_iommu=on`, `default_hugepagesz`, `hugepagesz`, `nr_hugepages`, `pci=resource_alignment`, `vfio-pci.ids`); requires host reboot |158| Hugepages | hugepage *reservation* change (`/sys/kernel/mm/hugepages/*/nr_hugepages`, `sysctl vm.nr_hugepages`); hugepage *mount* change (`mount -t hugetlbfs`); this is global state shared with every DOCA / DPDK process on the host |159| PCIe state | PCIe rebind / `echo > /sys/bus/pci/.../{bind,unbind,remove,rescan}`; representor enable/disable; eswitch mode change (`devlink dev eswitch set ... mode {switchdev,legacy}`); link down/up on a port currently carrying traffic |160| BlueField reboot class | BlueField cold reboot, BlueField warm reboot to apply `mlxconfig`; opening any RShim node other than `misc` (even `cat /dev/rshimN/boot` starts a boot cycle and resets the BlueField; read only `/dev/rshimN/misc`); any change whose blast radius is *"every hosted service on this DPU restarts"* |161| Per-artifact cross-link | any per-artifact skill's `## Safety policy` cross-links here for the cross-cutting rule body |162163When any cell above fires, the agent MUST load this skill **before**164composing the first sentence of the answer. For production it MUST165walk the change-application discipline in this order:166## configure (plan) →167`## test` (representative replica change + rollback168rehearsal) → `## modify` (production apply) →169`## run` (production verification) →170`## debug` (debug / rollback). It MUST cite the171activation explicitly in the answer (e.g. *"because this touches172`mlxconfig`, the answer follows the `doca-hardware-safety`173discipline …"*) so the user can audit the reasoning.174175The activation is **mandatory, not advisory.** The most common failure mode this overlay prevents is *"the agent recommended a `mlxconfig` change with no maintenance window, no out-of-band path, and no rollback statement, the user applied it, the management link dropped, and the box was unrecoverable without a physical console."* The cost of one unjustified activation (a few extra paragraphs in the answer) is trivial compared to the cost of one missed activation.176177## Refuse-and-escalate is a hard rule178179If any of the following is true, the agent MUST stop and refuse to recommend the change — not soften the warning, not proceed with a *"this is risky but here's how"* answer, not defer the rollback question to *"you should think about that"*:1801811. The change has no documented rollback path AND the user cannot provide one. (Per ## Safety policy *rollback-must-be-documented* rule.)1822. The change is link-breaking AND the host has no out-of-band access path. (Per ## Safety policy *out-of-band-precondition* rule.)1833. The change touches hardware state AND the user has not confirmed an184 explicit, time-boxed maintenance window. (Per185 ## Safety policy186 *maintenance-window* rule.)1874. Production application is contemplated before the change and its188 rollback have passed on a representative non-prod replica. This189 refusal is intent-based: it applies to a plan, recommendation, or190 next action that would reach production early, not only when the191 user explicitly asks for "direct application." A replica192 mismatched on the required hardware, firmware, kernel, module, or193 function-topology axes does not satisfy the gate; obtain a194 representative replica or refuse and escalate. (Per195 ## test *replica-first* rule.)196197In each of these cases the correct answer shape is *"this change requires X (here is why); the bundle refuses to recommend it without X; here is the route to obtain X"* — not silence and not improvisation. The refuse-and-escalate rule is what makes the bundle's hardware-safety guidance trustworthy to production operators.198199Do **not** load this skill for general DOCA orientation (use200`doca-public-knowledge-map/SKILL.md`),201for first-time install or env-class debug (use202`doca-setup/SKILL.md`), or for purely program-side203debug that does not touch hardware state (use204`doca-debug/SKILL.md` or205`doca-programming-guide/SKILL.md`).206207## What this skill provides208209This is a **thin loader**. The body keeps only the orientation needed210to pick the right next file. The substantive content lives in two211companion files:212213- the capabilities companion — the meta-policy surface: the class of changes214 in scope (the pre-flight inventory taxonomy, the215 `mlxconfig`-class / firmware-burn / kernel-boot-parameter216 groupings), the cross-cutting safety policy that every per-artifact217 `## Safety policy` overlays, the failure modes the policy prevents218 (bricked-link, runaway-burn, silent-mode-change, missing-rollback),219 the observability gate the operator must satisfy before any220 workload moves, and the thin version-compatibility overlay that221 redirects to `doca-version/SKILL.md`.222- the tasks companion — the change-application workflows: `## configure` (the223 pre-flight inventory + out-of-band + maintenance-window plan),224 `## build` (routing stub — hardware-touching changes do not produce225 build artifacts), `## modify` (the apply-the-change discipline,226 including the `mlxconfig` cold-power-cycle rule and the227 firmware-burn discipline), `## run` (the post-change verification228 gate), `## test` (the replica-first smoke), `## debug` (the229 rollback ladder + the refuse-and-escalate escape valve), and the230 `## Deferred task verbs` block.231232## Loading order2332341. Read this skill first to confirm the user's question is in235 scope (the agent is about to recommend a change that touches236 hardware state on a live system).2372. **For the class of changes in scope, the meta-safety policy, the238 failure-mode taxonomy, the observability gate, and the239 version-overlay redirect, see the capabilities companion.**2403. **For the apply-a-change workflow — pre-flight inventory →241 out-of-band → maintenance window → apply → verify → rollback —242 see the tasks companion.**2434. The per-artifact specifics (which exact firmware slot to flip,244 which exact kernel parameter the operator needs, which exact245 container tag the operator must roll back to) live in the matching246 per-artifact skill's `## Safety policy` overlay. This skill does247 NOT name those specifics; the agent reaches them by routing back248 to the per-artifact skill after the meta-policy is satisfied.249250## Related skills251252- `doca-version/SKILL.md` — the four-way match253 rule and the host ↔ BlueField BFB ↔ container-tag pairing. Every254 hardware-touching change has a version dimension; this skill's255 `## Version compatibility` overlay is a 3-5 line redirect to256 `doca-version` for the body.257- `doca-setup/SKILL.md` — env-class checks that258 precondition a hardware-touching change (hugepages, IOMMU mode,259 `pkg-config`, representor visibility). The pre-flight inventory in260 this skill's `## configure` cross-links to `doca-setup` for the261 env-class half of the inventory.262- `doca-debug/SKILL.md` — the cross-cutting layered263 debug ladder. When a hardware-touching change goes wrong, the264 rollback ladder in this skill's `## debug` hands off to265 `doca-debug` once the rollback has restored a known state and the266 symptom now lives at a software layer.267- `doca-structured-tools-contract/SKILL.md` —268 the JSON schemas the agent prefers when present. The269 `collect-host-state` / `collect-dpu-state` schemas are the270 structured form of this skill's pre-flight inventory; the agent271 uses them as the one-shot answer when the host has the helpers272 installed.273- `doca-container-deployment/SKILL.md` —274 the canonical container-deployment recipe shared across DOCA275 services. Several hardware-touching changes (BlueField cold276 reboot, BFB reflash) interrupt every hosted service container on277 the BlueField; the rollback path quotes the278 `doca-container-deployment` re-deploy shape.279- `doca-programming-guide/SKILL.md` —280 program-side preconditions (capability discovery,281 validate-before-commit). The post-change verification gate in this282 skill's `## run` cross-links there for the program-side283 observability surface that must be visible before any production284 workload moves.285- Per-artifact `## Safety policy` anchors in each in-bundle286 service / library / tool skill — e.g. the firmware-slot287 precondition in `doca-argus/SKILL.md`,288 `doca-dms/SKILL.md`,289 `doca-firefly/SKILL.md`,290 `doca-urom-svc/SKILL.md`; the291 device-touching libraries292 (`doca-flow/SKILL.md`,293 `doca-rdma/SKILL.md`,294 `doca-eth/SKILL.md`,295 `doca-pcc/SKILL.md`,296 `doca-rmax/SKILL.md`); and the297 hardware-touching tools (e.g.298 `doca-spcx-cc/SKILL.md`,299 `doca-pcc-counters/SKILL.md`).300 Every in-bundle artifact skill's `## Safety policy` overlays301 this meta-policy with artifact-specific safety. The cross-link is302 intentionally bidirectional: per-artifact skills link here for303 the meta-policy; this skill enumerates the in-bundle overlays in304 ## Safety policy305 as "skills that overlay this meta-policy". The externally-306 productized analogs (`doca-virtio-net`, `doca-snap`, `doca-hbn`,307 BlueMan, DPF) are NOT in-bundle skills — their safety policies308 live in product documentation reached through309 `doca-public-knowledge-map ## Externally-productized DOCA310 software` (`doca-public-knowledge-map/SKILL.md#externally-productized-doca-software--not-in-this-bundle-but-here-is-where-to-route`).