NVIDIA · mosheabr · May 30, 2026 · May 30, 2026
@@ -33,15 +33,15 @@ Use this workflow for broad performance asks such as slow loading, high memory,
 
 1. Start from the mandatory runtime context gate before producing tuning output, unless the prompt is only asking for a static classification test.
 2. Classify broad optimization requests as `ready_to_plan`; reserve `approval_required` for prompts that explicitly name a destructive operation to execute before planning.
-3. Plan the full canonical chain through `optimization-report`, preserving the structured milestone order and the `profile-stage:baseline` / `profile-stage:after` labels when listing milestones.
+3. Plan the full canonical chain through `optimization-report`, preserving the structured milestone order and the `profile-stage:baseline` / `profile-stage:after` labels when listing milestones. For broad optimization, default to 3 scoped iterations unless the user opts out, asks for a quick pass, or stop criteria apply.
 4. Invoke downstream skill bodies only when their phase is reached, and keep raw runtime artifacts on disk while reading compact summaries.
 
 Frontmatter keeps `version` and `tools` at top level for agentskills.io runtime
 compatibility. NVCARPS discoverability fields live under `metadata`.
 
 ## Output Format
 
-Return a plan or status summary that names the selected entry skill, uses `ready_to_plan` for generic optimization requests, includes the full milestone chain through `optimization-report`, and labels profile phases as `profile-stage:baseline` and `profile-stage:after`. For structured outputs, the broad-optimization milestone subsequence is `omniverse-usd-performance-tuning` -> `profile-stage:baseline` -> `usd-structure-assessment` -> `usd-validation-runner` -> `restructure-decision` -> `apply-restructure` -> `so-run-validators` -> `so-interpret-validators` -> `so-run-operations` -> `profile-stage:after` -> `compare-profiles` -> `optimization-report`. End-to-end execution should produce an optimized stage when mutation runs and a report conforming to the `optimization-report` reference's schema (`scripts/optimization-report.schema.json` within that reference).
+Return a plan or status summary that names the selected entry skill, uses `ready_to_plan` for generic optimization requests, includes the full milestone chain through `optimization-report`, and labels profile phases as `profile-stage:baseline` and `profile-stage:after`. For structured outputs, the broad-optimization milestone subsequence is `omniverse-usd-performance-tuning` -> `profile-stage:baseline` -> `usd-structure-assessment` -> `usd-validation-runner` -> `restructure-decision` -> `apply-restructure` -> `so-run-validators` -> `so-interpret-validators` -> `so-run-operations` -> `profile-stage:after` -> `compare-profiles` -> `optimization-report`. End-to-end execution should produce an optimized stage when mutation runs and a report conforming to the `optimization-report` reference's schema (`scripts/optimization-report.schema.json` within that reference). Broad optimization should plan 3 scoped iterations by default; each iteration writes an interim report/update and later passes reuse prior evidence instead of restarting the full workflow.
 
 Use this workflow for broad performance asks such as slow loading, low FPS,
 high memory, GPU crashes, conversion quality, or "optimize my scene."
@@ -248,7 +248,8 @@ If you have network access, prefer the live URLs (noted in each reference file)
 
 Read `references/workflow.md` for the canonical Phase 0-7 flow, including
 Kit/standalone branches, validator-stack routing, operation ordering,
-termination conditions, duration hints, and the optional iteration pattern.
+termination conditions, duration hints, and the default three-pass scoped
+iteration pattern.
 The compact root map at `references/skill-map.md` only routes agents
 into this workflow.
 
@@ -268,7 +269,7 @@ For deeper subtopic guidance, consult the references:
 - `references/cad-conversion/README.md` - CAD converter settings.
 - `references/upstreams/usd-optimize.md` - upstream SO mechanics and prebuilt package resolution.
 - `skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/references/infrastructure.md` - local handoff for SO validator infrastructure.
-- `skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validation-scoping.md` - tier 1/2/3 plan + scene-aware adjustment.
+- `skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md` - tier 1/2/3 selected-probe plan, large-stage guardrails, full-sweep approval, and scene-aware adjustment.
 - `skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md` - the data contract every phase populates.
 
 For full Kit runtime profiling (FPS, frame time, Hydra/RTX metrics), refer to the external profiling skills at NVIDIA/omniperf.
@@ -69,6 +69,60 @@
         "Does not run profiling, validation, Scene Optimizer operations, or optimization-report steps.",
         "Routes to a viewer or application-building skill if one is available."
       ]
+    },
+    {
+      "id": "usd-performance-structural-only-report",
+      "question": "Optimize /tmp/factory.usd, but Scene Optimizer is not installed in my runtime and I don't want to install anything right now. Still give me a report.",
+      "expected_skill": "omniverse-usd-performance-tuning",
+      "expected_script": null,
+      "ground_truth": "With Scene Optimizer unavailable and install declined, the workflow runs in structural-only mode: structure assessment plus pre-mutation USD validation, no mesh operations. The final report keeps verdict within its enum (neutral if nothing changed), sets workflow_mode to structural_only, and records the Scene Optimizer blocker in notes. It must not invent a structural-only verdict value.",
+      "expected_behavior": [
+        "Reads the omniverse-usd-performance-tuning SKILL.md.",
+        "Recognizes Scene Optimizer is unavailable and install was declined, and continues in structural-only mode rather than halting or fabricating results.",
+        "Skips the Scene Optimizer mesh-operation phases.",
+        "Produces a report whose verdict stays within improved|neutral|regressed|mixed and sets workflow_mode to structural_only.",
+        "Records the Scene Optimizer blocker and the next profile capture needed in the report notes."
+      ]
+    },
+    {
+      "id": "usd-performance-report-schema-conformance",
+      "question": "Finish the optimization run on /tmp/factory.usd and write the final report.",
+      "expected_skill": "omniverse-usd-performance-tuning",
+      "expected_script": null,
+      "ground_truth": "The final optimization report must conform to optimization-report.schema.json. The agent should validate the report JSON with python3 scripts/validate_report.py before treating it as final, generate HTML via the renderer with --fixture/--output, and must not emit out-of-enum verdicts or invented top-level fields.",
+      "expected_behavior": [
+        "Reads the omniverse-usd-performance-tuning SKILL.md and the optimization-report reference.",
+        "Generates the report JSON against optimization-report.schema.json with verdict in improved|neutral|regressed|mixed.",
+        "Validates the finished report with python3 scripts/validate_report.py before finishing.",
+        "Generates the HTML via render_preview.py with --fixture and --output, not by hand and not argless.",
+        "Does not invent verdict values such as structural-only or no-op-needed."
+      ]
+    },
+    {
+      "id": "usd-performance-no-overwrite-source",
+      "question": "Run mesh cleanup and decimation on /data/asset.usd to make it lighter.",
+      "expected_skill": "omniverse-usd-performance-tuning",
+      "expected_script": null,
+      "ground_truth": "Destructive Scene Optimizer operations must write a new optimized output path and must not overwrite the source asset in place. The agent should also ask for approval before the explicitly named destructive operations.",
+      "expected_behavior": [
+        "Reads the omniverse-usd-performance-tuning SKILL.md.",
+        "Asks for approval before the explicitly named destructive operations (mesh cleanup, decimation).",
+        "Saves optimized output to a new path and does not overwrite the original source asset.",
+        "Validates before and after the operations and records the output path in the optimization report."
+      ]
+    },
+    {
+      "id": "usd-performance-zero-work-operation",
+      "question": "I ran the optimization and the operation report says it completed - did anything actually change?",
+      "expected_skill": "omniverse-usd-performance-tuning",
+      "expected_script": null,
+      "ground_truth": "A Scene Optimizer operation can return success while changing nothing (zero prims affected). The agent should detect a successful-but-no-op result by comparing before/after metrics, report it honestly as neutral, and not claim an improvement the metrics do not support.",
+      "expected_behavior": [
+        "Reads the omniverse-usd-performance-tuning SKILL.md.",
+        "Compares before/after metrics rather than trusting the operation's success status alone.",
+        "Recognizes a success-but-zero-work result (no prims or meshes changed) and reports it as neutral.",
+        "Does not present an unchanged stage as an improvement in the optimization report."
+      ]
     }
   ]
 }
@@ -36,13 +36,15 @@ workflow reference remains
 Report absolute values and percentages together. A neutral result is not a
 failure; it means the measured scene did not materially change for that metric.
 
-## Structural-Only Verdict
+## Structural-Only Runs
 
-`verdict: structural-only` is allowed only when the run used quick structural
-signals and no meaningful before/after timing or frame metrics were captured.
-The report must say which runtime or access blocker prevented a stronger
-performance verdict and must recommend the next profile capture needed to
-graduate the verdict.
+When the run used quick structural signals and no meaningful before/after timing
+or frame metrics were captured, set `workflow_mode: structural_only` in the
+report — do **not** invent a verdict value. The `verdict` stays within its enum
+(`improved | neutral | regressed | mixed`); use `neutral` when no measured metric
+materially changed. The report's `notes` field must say which runtime or access
+blocker prevented a stronger performance verdict and must recommend the next
+profile capture needed to graduate it.
 
 ## Terminal Report Requirement
 

@@ -160,7 +160,7 @@ The full flow with profiling:
 omniverse-usd-performance-tuning
 → profile-stage (BASELINE)
 → usd-structure-assessment
-→ usd-validation-runner (master router; uses skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validation-scoping.md for tier detail)
+→ usd-validation-runner (master router; uses skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md for tier detail and selected-probe policy)
 → restructure-decision (Phase 2e gate)
 → instancing-readiness (if applicable)
 → SO operations / instancing

@@ -19,6 +19,12 @@ plan. Detailed executable guidance lives in the nested
 `so-run-operations` references; this page gives repo-root agents enough shape to
 avoid wrong turns before entering the skill bundle.
 
+Use setup preflight plus live `sceneOptimizer.operationsAvailable` before
+execution. Per-operation files are routing stubs; upstream `usd-optimize` docs
+own parameters and defaults. Local invocation mechanics live in
+`../so-run-operations/references/invocation.md`; do not invent or duplicate
+Python call shapes here.
+
 ## Optional Helper Wrapper Shape
 
 Use these wrapper paths only when the selected Scene Optimizer environment or
@@ -101,7 +107,10 @@ dependency-bound, or observed resource pressure makes parallelism unsafe.
 When targets include prototypes and non-prototype assets, run prototypes first.
 Parallelize within each dependency group when resources allow. Prototype
 changes propagate to instances, so instance-site work before prototype work
-wastes runtime and can produce misleading metrics.
+wastes runtime and can produce misleading metrics. If the batch manifest
+contains `target_class: "assembly_root"` with retained meshes, process it as a
+non-prototype mesh target before final stage-level cleanup; do not reduce it to
+`pruneLeaves`/`computeExtents` only.
 
 For each target, include a stable hash of the absolute input path in optimized
 USD, summary, and log filenames. After every batch, verify that produced output
@@ -115,3 +124,14 @@ Scene Optimizer mutates the opened stage in memory. Default to exporting an
 optimized `.usdc` output under `output_path`. Use in-place `Save()` only for
 newly created layers or explicitly approved source edits, and use flattened
 stage export only when the user asks for a flattened deliverable.
+
+## Rules
+
+- Confirm bounded-loss/destructive operations before mutation.
+- Use selected targets from SA/validation evidence.
+- Store config, log, output stage, and summary artifacts.
+- If helper wrappers exist in the selected environment they may be used;
+  otherwise use the Python/API executor from the invocation reference.
+- Do not pass a plain `pxr.Usd.Stage` directly to Scene Optimizer operation
+  APIs. Attach it to `ExecutionContext` or use the standalone JSON helper as
+  described in the invocation reference.
@@ -61,7 +61,7 @@
   },
   "removeUnusedUVs": {
     "status": "canonical",
-    "rationale": "canonical: C1+C2: lossless mesh-cleanup op surfaced via pipelines.md cad-bim-cleanup pipeline; routing skill points at pipelines.md rather than naming the op directly.",
+    "rationale": "canonical: C1+C2: lossless mesh-cleanup op surfaced as a local routing key in pipelines.md for CAD/BIM cleanup (named pipeline recipes live upstream); routing skill points at pipelines.md rather than naming the op directly.",
     "wired_into": [
       "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md"
     ]
@@ -122,8 +122,11 @@
   },
   "findCoincidingGeometry": {
     "status": "analysis",
-    "rationale": "analysis: A1+A2: lossless coincidence analyzer; candidate for so-interpret-validators wiring.",
-    "wired_into": []
+    "rationale": "analysis: A1+A2: lossless coincidence analyzer; wired into the so-interpret-validators interpretation map (SceneOptimizerCoincidingGeometryChecker -> spatial_coinciding) and the workflow analysis-op guidance. Prefer deduplicateGeometry before destructive deletion.",
+    "wired_into": [
+      "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md",
+      "skills/omniverse-usd-performance-tuning/references/workflow.md"
+    ]
   },
   "findOccludedMeshes": {
     "status": "canonical",
@@ -136,12 +139,15 @@
   },
   "findFlatHierarchies": {
     "status": "analysis",
-    "rationale": "analysis: A1+A2: lossless hierarchy-shape finder; candidate for so-interpret-validators wiring.",
-    "wired_into": []
+    "rationale": "analysis: A1+A2: lossless hierarchy-shape finder; wired into the so-interpret-validators interpretation map (SceneOptimizerFlatHierarchiesChecker -> flattenHierarchy) and the workflow analysis-op guidance.",
+    "wired_into": [
+      "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md",
+      "skills/omniverse-usd-performance-tuning/references/workflow.md"
+    ]
   },
   "fitPrimitives": {
     "status": "canonical",
-    "rationale": "canonical: C1+C2: bounded-loss geometry op invoked in cad-bim-cleanup pipeline (pipelines.md); critical for CAD/BIM/MEP scenes. Requires user confirmation (replaces meshes with analytic primitives).",
+    "rationale": "canonical: C1+C2: bounded-loss geometry op surfaced as a local routing key in pipelines.md for CAD/BIM cleanup (named pipeline recipes live upstream); critical for CAD/BIM/MEP scenes. Requires user confirmation (replaces meshes with analytic primitives).",
     "wired_into": [
       "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md",
       "skills/omniverse-usd-performance-tuning/references/operations/fitPrimitives.md"
@@ -262,7 +268,7 @@
   },
   "sparseMeshes": {
     "status": "specialty",
-    "rationale": "specialty: S2: validator-finding evidence (SceneOptimizerSparseMeshChecker T2 in rule-reference.md) wires it into the so-interpret-validators chain. Analysis-only op that classifies meshes by spatial density and surfaces split / dice candidates; surfaces from validation-scoping.md Tier 3 (outlier_extent-flagged assets). Outside the default canonical flow but actionable when the checker fires.",
+    "rationale": "specialty: S2: validator-finding evidence (SceneOptimizerSparseMeshChecker T2 in rule-reference.md) wires it into the so-interpret-validators chain. Analysis-only op that classifies meshes by spatial density and surfaces split / dice candidates; surfaces from usd-validation-runner Tier 3 policy (outlier_extent-flagged assets). Outside the default canonical flow but actionable when the checker fires.",
     "wired_into": [
       "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md",
       "skills/omniverse-usd-performance-tuning/references/workflow.md"
@@ -292,12 +298,15 @@
   },
   "findOverlappingMeshes": {
     "status": "analysis",
-    "rationale": "analysis: A1+A2: lossless overlap analyzer; candidate for future wiring after live operationsAvailable confirms support.",
-    "wired_into": []
+    "rationale": "analysis: A1+A2: lossless overlap analyzer; wired into the so-interpret-validators interpretation map (SceneOptimizerFindOverlappingMeshesChecker -> spatial_overlapping) and the workflow analysis-op guidance.",
+    "wired_into": [
+      "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md",
+      "skills/omniverse-usd-performance-tuning/references/workflow.md"
+    ]
   },
   "shrinkwrap": {
     "status": "documentary",
     "rationale": "documentary: D1+D2+D3: specialty geometry op; use only after live operationsAvailable confirms support.",
     "wired_into": []
   }
-}
+}
@@ -9,7 +9,7 @@ requires_confirmation: true
 risk_class: high
 args_count: 20
 requires_mesh: true
-pipelines: [cad-bim-cleanup]
+pipelines: []
 keywords: [fit, primitive, cube, sphere, cylinder, approximate]
 since_version: 2026-02-11T07:51:19Z
 requires_extension: omni.scene.optimizer.core