/doca-hardware-safety

license: Apache-2.0
name: doca-hardware-safety
description: >
  Use this skill whenever the agent is about to recommend or apply a
  change that touches DPU / NIC hardware state on a live system —
  mlxconfig firmware-parameter write, NIC firmware burn, BFB reflash,
  NIC ↔ DPU mode flip, SR-IOV or device-emulation slot enable, kernel
  boot-parameter change (IOMMU, hugepages, VFIO), PCIe rebind /
  rescan / link-state flip, or BlueField cold reboot. Wraps the
  change in pre-flight inventory, OOB reachability, a maintenance
  window, the mlxconfig cold-power-cycle rule, replica rehearsal, and
  rollback. Trigger even when the user does not say "hardware safety"
  — implicit phrasings: "flip BlueField mode over SSH", "enable
  SR-IOV and reboot", "burned firmware but mlxconfig shows old
  value", "reflashed BFB and lost representors", "reflash during
  business hours", "vendor says this is one-way". Refuse for general
  DOCA orientation (doca-public-knowledge-map), install or env debug
  (doca-setup), and program-side debug (doca-debug,
  doca-programming-guide) — those belong to other skills.
metadata:
  kind: library
compatibility: >
  No DOCA install required to read this skill (it is an overlay
  loaded against any DOCA artifact skill); the validation steps
  within DO require a live DOCA install at /opt/mellanox/doca with a
  BlueField DPU or ConnectX NIC, plus out-of-band console
  reachability (BMC, RShim, or operator-managed console) for any
  link-breaking change.

DOCA hardware safety

**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 [`TASKS.md`](TASKS.md) 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 [`CAPABILITIES.md`](CAPABILITIES.md) 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.

Example questions this skill answers well

The CLASSES of hardware-safety questions this skill is built to answer, each with one worked example. The agent should treat the *class* as load-bearing — the worked example is a single instance.

• **"I'm about to apply a hardware-touching change. What do I have to

capture *before* I touch anything?"** — worked example: *"the per-artifact skill told me to flip a firmware-level emulation slot; what do I capture first?"*. Answered by the pre-flight inventory in [`TASKS.md ## configure`](TASKS.md#configure) plus the inventory taxonomy in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes).

• **"This change might drop the link I'm using to manage the

BlueField. Is that safe?"** — worked example: *"I'm about to flip the BlueField between NIC and DPU mode over the same management link"*. Answered by the out-of-band access rule in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy) plus the OOB-precondition gate in [`TASKS.md ## configure`](TASKS.md#configure).

• **"The per-artifact skill said to write an `mlxconfig` parameter,

then reboot. Is that the right sequence?"** — worked example: *"the storage-emulation skill told me to enable a firmware slot via `mlxconfig` and then warm-reboot to apply it"*. Answered by the `mlxconfig`-class rule in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) plus the apply-with-cold-power-cycle workflow in [`TASKS.md ## modify`](TASKS.md#modify).

• **"My deployment plan reflashes the BlueField BFB during business

hours. Is that OK?"** — worked example: *"I have a one-hour window during the day; can I reflash now?"*. Answered by the maintenance-window discipline in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy) plus the firmware-burn workflow in [`TASKS.md ## modify`](TASKS.md#modify).

• **"How do I prove the change works *before* I touch production?"**

— worked example: *"the change is small; can I skip the lab replica"*. Answered by the replica-first rule in [`TASKS.md ## test`](TASKS.md#test) plus the pre-hardware-validation pattern in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes).

• **"How do I roll back if this change goes wrong?"** — worked

example: *"I just reflashed the BFB and the host can't see the representors anymore"*. Answered by the rollback ladder in [`TASKS.md ## debug`](TASKS.md#debug) plus the rollback-must-be-documented rule in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy).

• **"This change doesn't have a documented rollback. Should I still

apply it?"** — worked example: *"the vendor says this firmware rev is one-way"*. Answered by the refuse-and-escalate rule in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy) plus the escalation path in [`TASKS.md ## debug`](TASKS.md#debug).

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`](../../AGENTS.md#cross-cutting-overlay-activation-triggers), mirrore