/holohub-debug-build-run

name: holohub-debug-build-run
description: "Use when a concrete ./holohub command fails, hangs, regresses, or returns wrong output and needs reproducible diagnosis and verification."
license: Apache-2.0
metadata:
  author: "Holoscan Team <holoscan-team@nvidia.com>"
  compatibility: "holoscan-cli>=4.5.0"
  github-url: "https://github.com/nvidia-holoscan/holohub"
  tags:
    - holoscan
    - holohub
    - debugging

Debug HoloHub commands

Purpose

Turn one concrete wrapper failure into a minimally fixed, reproducible passing command with focused regression proof.

Inputs

Require:

• the affected user-provided HoloHub checkout;
• one exact failing, hanging, regressed, or semantically wrong `./holohub`

command;

• expected and observed results, relevant inputs, and the point where progress

stops;

• the runtime needed to reproduce the command.

Route non-failing app development to `holohub-app-lifecycle`, non-failing Module work to `holohub-module-lifecycle`, and first-time SDK installation to `holoscan-setup`. If the matching skill is unavailable, preserve the handoff context and name the skill to install. Do not manufacture a failure.

Prerequisites

• Always read the [CLI contract](references/holohub-cli-contract.md).
• Read the [debug workflow](references/debug-workflow.md) for layer

classification, observability, hypothesis testing, cleanup, and proof.

• Read only the relevant section of

[version-sensitive diagnostic priors](references/known-issues.md).

The affected checkout's `AGENTS.md`, local help, exact reproduction, schemas, and source are the live technical authority where they do not conflict with user, system, or safety constraints.

Instructions

If the request is planning-only or forbids execution, do not begin the steps below. Return only the proposed diagnostic order, evidence, approval boundaries, and proof requirements; do not run commands or change files, caches, artifacts, privileges, or environments.

1. **Freeze the reproduction.** Record the exact command, exit status or hang boundary and observation deadline, first useful error, expected versus observed result, full HEAD, concise status, and relevant input/image/artifact identities. 2. **Identify syntax and environment.** Read wrapper and subcommand help. Capture `version --json`, `env-info --json`, relevant `env-check --json`, and `status --json`, reviewing sensitive values before sharing. 3. **Locate the failing phase.** Separate launcher bootstrap from the verb, then distinguish host, image setup, container, configure/build/test/package, and application behavior. 4. **Preview the identical shape.** Add only locally supported preview and verbosity flags. Do not change project, mode, language, build type, image, inputs, devices, output, or other effect-bearing arguments. 5. **Reproduce once without edits.** Capture the smallest complete causal section, separate from shutdown noise. If the command or its options clear cached artifacts, including `clear-cache` or `test --clear-cache`, review the resolved affected paths and obtain explicit user authorization before reproduction; receiving a failing-command report is not approval for cache cleanup. For a hang, preserve all effect-bearing arguments but enforce an external timeout derived from the recorded hang boundary; record the deadline, termination signal, exit status, and whether child wrapper or container processes remain. If it no longer reproduces, compare revision, state, inputs, image, cache, display/devices, and environment, then report the mismatch rather than inventing a fix. 6. **Test one boundary and hypothesis.** Choose one primary layer, state a falsifiable explanation, change one variable, and record the result. Read source only after narrowing ownership. Revert diagnostic-only changes. 7. **Fix minimally.** Change the owning layer without unrelated refactoring, broad dependency upgrades, or public-contract changes. Add a focused deterministic regression test when possible; if infeasible, record why and use the nearest repeatable boundary check. 8. **Keep cleanup separate.** Never clear caches speculatively. If stale state is proved, preview the narrowest `clear-cache` scope, review every resolved path, and obtain explicit user approval before clearing those paths. 9. **Prove and restore.** For a mutating command, preview the post-fix identical shape before re-running it with the same inputs; the pre-fix preview is not proof of the resolved image, mounts, or child commands. Require the expected result, run the nearest focused test, inspect relevant artifacts, remove diagnostic-only changes, and compare final status with the baseline. After benchmark or instrumentation work, search for backups, rebuild normally to remove instrumented binaries and cached flags, then run a finite smoke case. For a Module, test its declared operators, demos, and consumer because `test <module>` is not module-scoped. Run `git diff --check`. 10. **Validate requested commits.** In a dirty checkout, restrict auto-fixing lint to task paths. Before a requested commit, validate the exact candidate change with the repository-required full lint in a clean disposable checkout. Inspect auto-fixes and rerun once; report persistent failure or churn instead of looping. Do not commit or push unless requested.

Troubleshooting

If the failure does not reproduce, report the state mismatch. If it belongs to a non-failing app or Module workflow, preserve the reproduction context and route it to the matching lifecycle skill.

Examples

• Diagnose a repeatable wrapper build failure: use this skill.
• Create or enhance an app with no failing command: use

`holohub-app-lifecycle`.

Limitations

• Preserve unrelated work. Do not reset, clean, delete, commit, push, change

host configuration, or broaden privileges without authorization