doca-debug

# DOCA debug

**Where to start:** This skill is the canonical layered-ladder
reference both [`doca-setup ## debug`](../doca-setup/TASKS.md#debug)
and [`doca-programming-guide ## debug`](../doca-programming-guide/TASKS.md#debug)
escalate to. If the symptom does not fit cleanly in env-class or
program-class, start at [`TASKS.md ## debug`](TASKS.md#debug) — the
full layered ladder lives there.

## Example questions this skill answers well

The CLASSES of debug questions this skill is built to answer, each
with one worked example.

- **"My DOCA build / link / runtime / program failed — which layer is
  it?"** — worked example: *"`ld` says `undefined reference to
  doca_flow_init` — which layer?"* Answered by the canonical layered
  ladder in [`TASKS.md ## debug`](TASKS.md#debug) (layer 4 = Link).
- **"How do I turn up verbosity for any DOCA library or tool?"** —
  worked example: *"My DOCA Flow program is silent — where do I get
  more log output?"* Answered by the trace-flavor / log-level surface
  in [`CAPABILITIES.md ## Observability`](CAPABILITIES.md#observability)
  + the run-with-verbosity workflow in
  [`TASKS.md ## run`](TASKS.md#run).
- **"How do I capture state for a forum question or bug report?"** —
  worked example: *"I'd like to file a forum question with reproducible
  context — what should I include?"* Answered by the
  capture-a-reproducible-state workflow in
  [`TASKS.md ## test`](TASKS.md#test).
- **"What does this DOCA tool's output mean / which tool answers
  this?"** — worked example: *"`doca_caps` returned nothing for RDMA
  — does that mean unsupported?"* Answered by the
  tool-vs-capability decision tree in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + cross-link to [doca-caps](../tools/doca-caps/SKILL.md).
- **"I'm debugging inside the NGC container — what's
  observable?"** — worked example: *"`hugepages` is empty inside the
  container; is that a real problem or a container thing?"*
  Answered by the container-specific debug constraints in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + [`TASKS.md ## debug`](TASKS.md#debug) layer 5 (Runtime).
- **"Where do I ask for help with this?"** — worked example: *"Where
  is the customer-facing DOCA forum and what should the post
  contain?"* Answered by the Developer-Forum routing rule in
  [`TASKS.md ## debug`](TASKS.md#debug) plus
  [doca-public-knowledge-map](../doca-public-knowledge-map/SKILL.md).

If the symptom is purely env-class, route to
[`doca-setup ## debug`](../doca-setup/TASKS.md#debug); if purely
program-class, route to
[`doca-programming-guide ## debug`](../doca-programming-guide/TASKS.md#debug).
This skill is the cross-cutting layer both call into.

## When to load this skill

Load this skill when the user is debugging anything DOCA-related — a build that won't compile, a link step that can't resolve a `doca_*` symbol, a runtime call that returns `DOCA_ERROR_*`, a packet that does not appear on the wire, a service that won't start, or a tool that returns no useful output. Concretely:

- The user reports a symptom and needs to find the layer that caused it (install / version / build / link / runtime / program).
- The user asks "how do I get more logs?" or "how do I turn up the verbosity?" for any DOCA library or tool.
- The user wants to capture state for a forum question or an internal bug report (the bundle does not own the internal-bug-report channel; it routes to the public DOCA Developer Forum).
- The user is reading a stack trace, a `valgrind` output, or a core dump from a DOCA program and wants to know where to look first.
- The user is debugging *inside* the NGC DOCA container and needs to know what is and is not observable from inside it.

Do **not** load this skill for:

- *"What is `DOCA_ERROR_BAD_STATE`?", "what error codes does DOCA return?"* — that is the cross-library *error taxonomy*, owned by [`doca-programming-guide CAPABILITIES.md ## Error taxonomy`](../doca-programming-guide/CAPABILITIES.md#error-taxonomy). This skill consumes that taxonomy; it does not redefine it.
- *"My `pkg-config` cannot find `doca-flow`", "hugepages are not mounted", "my representor isn't visible"* — those are env-class symptoms, owned by [`doca-setup ## debug`](../doca-setup/TASKS.md#debug). This skill is the canonical pointer that env-class debug ladder redirects to once the symptom escalates beyond install / version / build prerequisites.
- *Library-specific debugging* (Flow pipe trace, RDMA queue-pair state, Comch channel statistics) — those live in the matching library skill (e.g. [`doca-flow ## debug`](../libs/doca-flow/TASKS.md#debug)). This skill provides the cross-cutting debug ladder; library skills layer their library-specific debug surface on top of it.

## What this skill provides

This is a **thin loader**. The body keeps only the orientation needed to pick the right next file. The substantive debug material lives in two companion files:

- [CAPABILITIES.md](CAPABILITIES.md) — what *kinds of debug surface* DOCA exposes: the layered debug model (install / version / build / link / runtime / program), the read-only-first stance, version-availability of debug tools (e.g. `doca_caps` since DOCA 2.6.0), the cross-library error taxonomy (cross-link only — owned by `doca-programming-guide`), the observability primitives DOCA emits (`stderr` logs, `--sdk-log-level`, the `doca-<lib>-trace` build flavor, library counters), and the safety constraints on debug actions (read-only first, don't mutate install tree mid-investigation).
- [TASKS.md](TASKS.md) — the actual debug workflows: `## configure` (set up env for high-verbosity debug), `## test` (capture a reproducible state), `## debug` (the canonical layered ladder, the universal entry point that every library `## debug` redirects to), and the *Where to ask for help* routing (NVIDIA DOCA Developer Forum). Three other anchors (`build`, `modify`, `run`) exist for lint compliance and route to [