debug-operation

name: debug-operation description: Triage a failing Usd Optimize operation. Use when an op errors, silently no-ops, or returns unexpected output. version: "1.0.0" allowed-tools: Shell, Read, Grep, Glob metadata: author: NVIDIA Corporation tags: [debug, troubleshooting, operations]

Debug Operation

Structured workflow for triaging an operation that fails, produces unexpected output, or silently does nothing.

What this skill covers

Search this doc for keywords like verbose, analysisMode, argument key, silent no-op, mesh-less, instanced, libusd to jump.

• Step 1 — reproduce and capture the log.
• Step 2 — check the basics (argument keys, input stage).
• Step 3 — enable verbose + analysis mode.
• Step 4 — diagnose by failure pattern (tables for common failure modes).
• Operation-family cheat sheet — per-family gotchas.

Companion skills: run-operations (how to invoke), tune-parameters (when the op runs but the output isn't right), build (when the build itself is broken).

Step 1 — Reproduce and capture the log

Run the operation with full logging so the failure is captured on disk.

# POSIX — verbose + captureStats
tools/perf_operations/run.sh run "$ASSET" \
    --config '[{"operation":"executionContext","verbose":true,"captureStats":true},{"operation":"<key>","<arg>":"<val>"}]' \
    --no-save > /tmp/debug-run.log 2>&1

--no-save avoids writing a bad output file. The log captures both the C++ [INFO]/[WARN]/[ERROR] lines and the Python driver output.

If the user already has a log (e.g. from a prior run-operations run), skip this step and read their log directly.

Step 2 — Check the basics

Most "operation does nothing" reports fall into one of three categories. Check them in order before going deeper.

2a. Argument key mismatch

Operations silently ignore unknown argument keys. Verify every key in the user's config matches the operation's addArgument() declarations:

# Check the C++ source for the canonical argument keys
rg 'addArgument' source/operations/<key>/ --glob '*.cpp' --glob '*.h'

Or check the Parameters table in .agents/operations/<key>.md if a guide exists. Common mistakes:

• Camel-case vs snake-case (mergeVertices not merge_vertices).
• Plural vs singular (paths not path, meshPrimPaths not meshPrimPath).
• Boolean as string (true not "true" in JSON).

2b. Wrong operation key

The operation key is the first string argument to the Operation(...) base constructor, not the class name or the USD_OPTIMIZE_PLUGIN_INIT argument. Verify:

rg 'Operation\(' source/operations/<key>/ --glob '*.cpp' -A1 | head -5

2c. Input stage has no matching prims

Many operations scope work via a paths argument or operate only on specific prim types. If the stage has no prims matching the filter, the operation returns success but does nothing.

# Quick check: does the stage have meshes?
from pxr import Usd, UsdGeom
stage = Usd.Stage.Open("<asset>")
meshes = [p for p in stage.TraverseAll() if p.IsA(UsdGeom.Mesh)]
print(f"{len(meshes)} meshes")

Step 3 — Enable verbose and analysis mode

If the basics check out, run in analysis mode to see what the operation would do without mutating the stage:

from usd_optimize.core import ExecutionContext, UsdOptimizeCore
from pxr import Usd, UsdUtils

stage = Usd.Stage.Open("<asset>")
context = ExecutionContext()
context.usdStageId = UsdUtils.StageCache.Get().Insert(stage).ToLongInt()
context.analysisMode = 1
context.verbose = 1

success, error, output = UsdOptimizeCore.getInstance().executeOperation(
    "<key>", context, {<args>}
)

print("success:", success)
print("error:", error)
print("output:", output)

Not all operations support analysis mode. Check:

rg 'getSupportsAnalysis' source/operations/<key>/ --glob '*.cpp'

If the operation doesn't override getSupportsAnalysis, analysis mode is unavailable — fall back to running on a disposable copy of the stage.

For the full ExecutionContext flags reference, see .agents/operations/INVOCATION.md.

Step 4 — Diagnose by failure pattern

Hard failures (operation returns error)

Silent no-ops (operation returns success, nothing changed)

Unexpected output (operation ran but result is wrong)

Operation-family cheat sheet

Mesh operations (meshCleanup, decimateMeshes, merge, etc.)

• Require UsdGeomMesh prims. No meshes = no work.
• merge won't merge a boundary with a single mesh unless allowSingleMeshes: true.
• decimateMeshes can't reduce below the topological minimum per mesh. Assets with many small parts will overshoot the target percentage.
• reductionFactor is a percentage (0–100), not a fraction. 0.5 means "keep 0.5%", not "keep 50%".

Deduplication (deduplicateGeometry, deduplicateHierarchies)

• Prims with existing references/payloads are excluded from grouping.
• Instanced prims can't be authored in place — deinstance first.
• deduplicateHierarchies traverses from the stage's default prim. No default prim = no work.
• Material-related prims (Material, Shader, NodeGraph, Looks, Materials scopes) are intentionally skipped.

Analysis-only operations (findCoincidingGeometry, findFlatHierarchies, findOverlappingMeshes, findOccludedMeshes)

• These detect but don't fix. The "fix" is a separate operation (e.g. removePrims, flattenHierarchy).
• Results come back in output["analysis"] — inspect that dict.

Material operations (optimizeMaterials)

• convertToColor: true replaces material networks with flat colors. Unintended if the user didn't ask for it.

Hierarchy operations (flattenHierarchy, pruneLeaves)

• REQUIRES_MESH = False — these run on mesh-less stages too.
• flattenHierarchy has params that control depth; defaults may not flatten enough.

See also

• .agents/operations/<key>.md — per-operation parameter reference.
• .agents/operations/INVOCATION.md — ExecutionContext flags, API surface.
• .agents/skills/run-operations/SKILL.md — errors table for driver failures.
• .agents/skills/tune-parameters/SKILL.md — when the operation runs but output quality needs iteration.

Purpose

Provide a structured triage workflow for an Usd Optimize operation that fails, silently no-ops, or produces unexpected output. Unifies log reading, argument verification, verbose / analysis-mode invocation, and a per-family cheat-sheet of common failure patterns so the agent can move from a vague "it didn't work" report to a concrete root cause without guessing.

Prerequisites

• A built repo (./repo.sh build or repo.bat build) — verbose / analysis-mode invocation requires the bundled Python.
• The operation key (e.g. meshCleanup) and the user's invocation — config JSON, command line, or Python snippet — so the actual arguments are known.
• A reproducible invocation. If the failure is intermittent, capture a log first with --verbose --captureStats --no-save.

Limitations

• This skill does not patch C++ source — its output is a diagnosis, not a code fix. For changes to the operation itself, the user works in source/operations/<key>/ directly.
• Analysis mode is unavailable for operations that don't override getSupportsAnalysis(). The skill falls back to running on a disposable stage copy in those cases.
• Crashes / segfaults are surfaced as bug reports — the skill won't attach a debugger or symbolicate stacks.

Troubleshooting

This whole skill is a troubleshooting guide for Usd Optimize operations. The table below covers the meta-failure modes — when this skill itself can't make progress.