Pva Debug

NVIDIAOfficialCreated by Venkat BalanDistributed by NVIDIA

Skill
Workflow
Software development
Apache-2.0
Medium risk

From the author

Diagnose and narrowly repair one reproduced NVIDIA PVA operator failure. Use from OpGen or manually for compile, link, cuPVA lifecycle, dataflow, DMA, numerical, EMU-versus-hardware, runtime, or performance failures. Preserve the original evidence and return the repaired source to the caller for a fresh Build-Test.

— the description by Venkat Balan

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The pva-debug skill provides a structured, evidence-based approach to diagnosing and resolving failures in NVIDIA PVA operators. It requires a comprehensive Doctor report as input to ensure the environment, SDK version, and failure context are verified before proceeding. The skill follows a rigorous process: reproducing the failure, isolating the root cause through falsifiable hypotheses, applying a minimal code repair, and verifying the fix against the original failing case and relevant test matrices. It is designed to integrate into larger workflows like OpGen or function as a standalone diagnostic tool, ensuring that repairs are narrow, safe, and documented without modifying public APIs or performance test requirements.

What it does

Verifies failure evidence against SDK references and lock files.
Reproduces the exact failure signature without initial code changes.
Systematically tests falsifiable hypotheses for compile, runtime, or numerical errors.
Applies the smallest possible code repair to address the proven cause.
Validates the repair by running the original failing case and affected test matrices.
Generates a detailed debug report documenting the findings and the repair.

When to use it

When a PVA operator fails during build, link, or runtime execution.
When numerical discrepancies are detected between EMU and hardware results.
When performance regressions occur in a PVA operator.
When you need a structured, repeatable process to isolate and fix a specific operator bug.

Advantages

Ensures repairs are evidence-based and minimal, reducing the risk of side effects.
Maintains strict traceability by preserving original failure evidence.
Integrates seamlessly with existing build and test workflows.
Provides a standardized reporting format for debugging outcomes.

Usage examples

“Debug the failure in the conv2d_pva operator reported in doctor-report.md.”: The agent validates the report, reproduces the failure, identifies a numerical error in the DMA synchronization, applies a fix, and returns a report confirming the fix.
“Investigate why the pva_pool_op is failing on hardware but passing in EMU.”: The agent isolates the hardware-specific failure, tests hypotheses related to device integration, repairs the code, and verifies the fix on hardware.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/pva-debug/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip pva-debug.zip -d .agents/skills
```

Documentation by Venkat Balan

Debug a PVA operator

Find one demonstrated cause. Make the smallest safe repair. Do not declare the complete operator passed.

Resolve paths

SKILL_ROOT is the absolute directory containing this skill's SKILL.md, after resolving symlinks. Bundled files are relative to that directory. Resolve supplied relative paths against the invocation directory before changing directories. Reuse OpGen's WORK_DIR for its reports. For a direct call, use the supplied absolute report path, or resolve the caller's report work directory as WORK_DIR.

Get the inputs

Require:

A Doctor report that covers the failed capability.
Absolute source and artifact paths, plus a report path or work directory.
Caller identity: OpGen or a user with the same complete failure evidence.
Failed stage, exact command, return code, full log, and source identity.
Smallest known failing input, expected result, and tolerance.
SDK version, PVA generation, compiler backend, build mode, and target identity when relevant.
EMU and hardware results that already exist.
One-based attempt number and maximum attempts for an OpGen call.

Return BLOCKED before a source change when required evidence is absent or the attempt number is greater than the maximum.

Load the technical basis

Require Doctor's public-reference-corpus check to be PASS. Set SDK_REFERENCES to the report's absolute sdk_reference_root. Require a readable index.md and reference-lock.json, a lock SHA-256 matching the report's sdk_reference_lock_sha256, and the reported SDK version matching this task. If these fields are absent or no longer match, return BLOCKED and request a fresh Doctor report. Do not fall back to an installed package or CWD path. Read the pva-debug route in $SDK_REFERENCES/index.md. Before reading Markdown, check its SHA-256 against the lock outputs entry; return BLOCKED on a mismatch. Resolve links relative to each generated file. Use rg to find the narrow Markdown that matches the first failed stage.

For each product fact, record the SDK documentation root, local Markdown path, packaged source path, source SHA-256, version, and section or PDF page.

Use supplied or public implementations within the user's authorized scope and their license terms.

Preserve and reproduce the failure

Save the original source identity, uncommitted changes, command, return code, log, input, actual output, and expected output.
Reproduce the failure without a source change.
Reduce the input only when the failure signature stays the same.
Identify the first failed command, operation, or output.

Return NOT_REPRODUCED if the supplied source and command do not reproduce the failure. Do not make a speculative repair.

Diagnose one cause

Classify the first failure as:

Compile.
Link or device integration.
cuPVA API or lifecycle.
Dataflow, DMA, memory, or synchronization.
Numerical or output correctness.
EMU-pass but hardware-fail.
Target runtime.
Performance regression.

For each hypothesis:

State one falsifiable cause.
Name the supporting evidence.
Run the smallest diagnostic that can prove or reject it.
Save the command and result.
Reject an unsupported hypothesis before you test another.

Use the independent CPU reference and first wrong element for numerical work. Use hardware evidence for a hardware-only failure. Use target compiler listings and hardware profiles for a performance regression. Do not use EMU timing as PVA performance evidence.

Repair and check

Change only the code that the proved cause requires. Do not change the public API, required result, tolerance, or performance test to hide the failure.

Record each changed file and reason. Keep the original evidence unchanged. Write diagnostics and repair evidence to new files.

Then:

Rebuild the failed target.
Run the original failing case.
Run nearby affected cases.
Run the EMU matrix when source changed and EMU support is available or required. Missing optional EMU support is not a failure. Record SKIPPED_OPTIONAL when optional EMU support is absent.
Run the original hardware case for a hardware-only or performance failure.
Confirm that the original signature is absent.
Record commands, return codes, logs, outputs, and repaired source identity.

These checks prove only the narrow repair. Build-Test owns final verification.

Return control

Write the report with the debug report template. For an OpGen workflow, use $WORK_DIR/reports/debug-attempt-<number>.md. For a direct call, use the supplied absolute report path or $WORK_DIR/reports/debug-report.md.

Return one result:

REPAIRED: The original case and affected checks pass.
NOT_REPRODUCED: The supplied source and command do not reproduce the failure.
BLOCKED: Required evidence, source, toolchain, target, contract, or attempt budget is unavailable.

Return the report to the caller. Direct the caller to invoke $pva-build-test with the complete original matrix and repaired source. For an OpGen call, resume the existing OpGen workflow: REPAIRED requires fresh Build-Test, and other results require OpGen's final report. Do not reinvoke OpGen or end the overall run with only the Debug response.

Check public release notes before you identify an SDK limitation. Do not claim an SDK defect without direct evidence.

Files

ATTRIBUTION.mdAdded by AutoGineer925 B
BENCHMARK.md9.7 KiB
LICENSELicence file added by AutoGineer11.2 KiB
README.md7.6 KiB
SKILL.md5.8 KiB
agents/openai.yaml349 B
assets/debug-report-template.md1.2 KiB
config/skillspector-baseline.yaml400 B
evals/EVAL.md1.4 KiB
evals/config.yml167 B
evals/evals.json4.1 KiB
evals/files/unverified/doctor-report.md278 B
evals/files/unverified/failure.md317 B
skill-card.md4.4 KiB
skill.oms.sig6.3 KiB

README.md

PVA development skills

Agent skills for creating, changing, or repairing NVIDIA PVA operators in your PVA SDK application or PVA Solutions source tree. They turn requirements into code, verify it on Tegra hardware, and repair failures within a debug budget.

Skills

Skill	Purpose
Doctor	Check the SDK, toolchain, project, target, and SDK references.
Setup	Install missing SDK, NVVPU, and L4T runtime components, then rerun Doctor.
Spec	Define operator behavior, correctness tests, and the OpGen handoff.
OpGen	Generate and integrate the operator, then invoke Build-Test and Debug.
Build-Test	Build, verify correctness on hardware, and measure requested performance cases.
Debug	Diagnose and repair a reproduced failure.

Prerequisites

An authenticated coding agent with local skill support and shell/file access. See agent support below.
A development host running regular x86-64 Ubuntu supported by the requested SDK.
An Arm64 Jetson board running compatible Jetson Linux (L4T), with working key-based SSH and a trusted host key.
A matching SDK installation guide (file or URL), access to its installer, and administrative permissions for required installation steps.
A writable project: your PVA SDK application or a PVA Solutions source package or checkout. This is where OpGen adds or changes code. Install Git LFS if the project uses it.

When PVA Solutions is selected, Setup uses NVIDIA/PVA-Solutions by default and clones into the supplied project path, or $WORK_DIR/source when omitted. It reuses an existing source tree and accepts another repository or archive. Doctor checks the selected source and reports missing required files.

Run the agent and build tools on the development host. PVA_BUILD_MODE=L4T cross-compiles there for execution on the board. PVA_BUILD_MODE=EMU builds for emulation on the development host.

Setup installs or reuses the SDK, NVVPU, required build and reference tools, and board runtime. EMU is optional. Setup calls Doctor before making changes and again afterward; no existing Doctor report is required. Setup reads the installer URL from the guide. Supply a separate installer path or URL only when the guide does not provide one. The guide and installer must match the requested SDK release. Setup reads the board's installed BSP and checks SDK compatibility. Supply an expected BSP release only when you want to require a specific release.

Set up a workspace

Copy all six PVA skill folders from the public NVIDIA skills catalog into $HOME/pva-sdk-skills. Keep each folder's scripts, references, and assets. The resulting layout is $HOME/pva-sdk-skills/pva-setup/SKILL.md, and the same layout for the other five skills.

git clone --depth 1 https://github.com/NVIDIA/skills.git "$HOME/nvidia-skills"
mkdir -p "$HOME/pva-sdk-skills"
for pva_skill in pva-setup pva-doctor pva-spec pva-opgen pva-build-test pva-debug; do
  cp -R "$HOME/nvidia-skills/skills/$pva_skill" "$HOME/pva-sdk-skills/"
done

Use a separate workspace for each operator task. Replace the project path below with your writable PVA SDK application or PVA Solutions source directory.

mkdir -p "$HOME/operator_test/my_operator"
cd "$HOME/operator_test/my_operator"
ln -s "/absolute/path/to/your/project" source

pva_skill_dir=.claude/skills # For Codex, use .agents/skills
mkdir -p "$pva_skill_dir"
for pva_skill in "$HOME/pva-sdk-skills"/pva-*; do
  ln -s "$pva_skill" "$pva_skill_dir/"
done

Reload skills or restart the agent session after creating the links. source/ points to the project OpGen will modify; the surrounding workspace holds your inputs, generated configuration, and reports. Each skill carries its required scripts and templates. Install all six for the full workflow; OpGen invokes Build-Test and Debug by their installed skill names. Generated SDK references belong in references/sdk/ in this workspace. Doctor records their verified absolute location in its report.

Agent support

Claude Code: Used for the recorded operator runs and the commands below.
Codex: Supports local skills in .agents/skills, invoked with $pva-spec or another skill name. These skills include agents/openai.yaml metadata. OpGen uses the agent's available skill mechanism for Build-Test and Debug. Without a callable skill tool, it loads the child skill's SKILL.md and executes its full workflow before resuming OpGen with the reports and verdict.

Run Setup → Doctor → Spec → OpGen

Create requirements.md in the workspace: operator name/path, task mode (new, change, or repair), required behavior, supported inputs, API, and performance requirements. For an existing operator, include relevant source and test paths.

Run these headless Claude Code commands one at a time from the development host's workspace. Replace the guide and board settings below. Setup resolves the SDK release, installer, package names, and installation paths from the guide and package metadata. Package paths are not fixed in the skill. You can provide an explicit SDK release or path override when needed.

export PVA_OPERATOR_MAX_DEBUG_ATTEMPTS=3

# 1. Setup: check and prepare the host and board
claude -p "Run pva-setup for spec, opgen, and build-test.
Installation guide: http://docs.nvidia.com/pva/sdk/installation.html.
Target: user@<board-IP>; PVA generation: <generation for your board>.
Project: $PWD/source; work directory: $PWD."

# 2. Doctor: verify readiness after Setup
claude -p "Run pva-doctor for spec, opgen, and build-test using
$PWD/reports/pva-setup-report.md.
Project: $PWD/source; work directory: $PWD."

# 3. Spec: run after Doctor is ready
# Spec runs its finalizer to create and validate configure/opgen-inputs.json.
claude -p "Invoke pva-spec through the Skill tool using
$PWD/requirements.md and $PWD/reports/doctor-report.md.
Project: $PWD/source; work directory: $PWD."

# 4. OpGen: run after Spec returns CONFIGURED
claude -p "Invoke pva-opgen through the Skill tool using $PWD/configure/opgen-inputs.json."

Doctor writes $WORK_DIR/reports/doctor-report.md automatically. The examples use $PWD as the work directory so Spec and OpGen can use the resulting files.

OpGen runs Build-Test and invokes Debug as needed. Read the final result in reports/opgen-report.md.

See reference maintenance for SDK-reference regeneration and upgrades.

Maintaining the helpers

Spec owns finalize_opgen_inputs.py. OpGen ships an identical copy so handoff validation works when the skills are installed separately. After changing the Spec helper, update the OpGen copy too. Generated SDK references and operator reports belong in the operator workspace.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Venkat Balan

Publisher

NVIDIA (Official)

Distributed by

NVIDIA

Source

NVIDIA/skills · skills/pva-debug · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Venkat Balan or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download pva-debug.zip