---
name: remediate-assets
description: Use when a SimReady asset has failed a requirement and the user needs to know how to fix it. Reads the failed requirement from sr_specs and the test failure detail, then proposes a spec-grounded fix without editing the asset.
license: Apache-2.0
compatibility: Requires simready-benchmark (pip install simready-benchmark) and read access to the user's sr_specs directory. Reading the per-test failure detail also requires a completed run with result.json files under the output directory.
metadata:
  author: NVIDIA
  library: simready_benchmark
  version: "2026.05"
---

## Confirm the Installed Version

This skill ships inside the `simready-benchmark` wheel, so the copy installed with the framework matches the installed code. If you are working from a cached copy or from memory rather than the installed package, confirm the framework version with `simready-benchmark --version`, and treat `simready-benchmark --help` and `simready-benchmark --show-config` as the authoritative source for flags and configuration. `--show-config` also prints the resolved `sr_specs` source, which is the directory this skill reads requirements from. A field documented here might have changed in a different version.

## What This Skill Does

A SimReady asset failed a requirement during a test run. The user wants to understand what the requirement wants and how to make the asset pass. This skill standardizes the two reads that ground good advice, then proposes a fix the user applies in their own DCC tool or pipeline.

The skill does two reads and one combine:

1. Read the failed requirement from the user's sr_specs. This is what the requirement wants, in human-readable terms.
2. Read the test failure detail from the per-test `result.json`. This is how this asset specifically failed.
3. Combine the two into a concrete, spec-grounded fix proposal.

This skill never edits the user's asset. Refer to [Key Rules](#key-rules) for the bounded-scope contract.

## Prerequisites

Find out which requirements failed before remediating. The [diagnose-failures](../diagnose-failures/SKILL.md) skill walks the report and the event stream to list the failing tests and the requirement codes they cover. Carry forward two identifiers from that step:

- The failed requirement code, for example `RB.COL.001`.
- The feature ID the requirement belongs to, for example `FET003`.

You also need the path to the user's sr_specs directory (from `simready-benchmark --show-config`) and the output directory of the run (default `_testing/`). The per-test result.json lives at `<output_dir>/results/<asset-dir>/.simready/runtime/<test_name>/result.json`. For finding which requirements failed in the first place, refer to the [diagnose-failures](../diagnose-failures/SKILL.md) skill.

## Remediation Workflow

### Step 1. Read the Requirement From sr_specs

Locate the requirement in the user's sr_specs and read its human-readable text. The full directory shapes and field paths are in [references/sr-specs-lookup.md](references/sr-specs-lookup.md). The short version:

- Open the `config/*.json` files in sr_specs. Each file holds one `capability` object.
- Inside `capability.requirements[]`, find the entry whose `code` matches the failed requirement code (for example `RB.COL.001`).
- Read that entry's `message` (the human-readable requirement text) and its `name` and `tags`.
- Read the surrounding `capability.description` for the broader context of what the capability is for.
- Open the feature file under `features/` or `docs/features/` whose `id` matches the feature (for example `FET003`) and read its `display_name` so the advice names the feature the user sees in the report.

Consult the user's actual sr_specs for this. Requirement messages are authored per project and can differ from general knowledge. Do not answer from memory alone.

### Step 2. Read the Failure Detail From result.json

Open the per-test result file for the failing test:

```
<output_dir>/results/<asset-dir>/.simready/runtime/<test_name>/result.json
```

Read these fields:

- `message`. The failure text the test wrote through `ctx.fail(message)`. For a skipped prerequisite it carries the skip reason instead.
- `failure_details`. The structured dict the test passed as the second argument to `ctx.fail(message, details)`, when it provided one. It is `null` when the test passed or attached no details. This carries named values the test author chose to attach to the failure.
- `metrics`. The named values the test recorded through `ctx.add_metric(name, value, unit)`. Each entry is a dict of the shape `{"value": <value>, "unit": <unit or null>}`. This is where a numeric measurement below a threshold shows up, for example a settle height or a pixel-difference ratio.
- `warnings` and `logs`. Non-fatal notes and log lines the test emitted, useful when the `message` is terse.

The `message`, `failure_details`, and `metrics` together are the asset-specific evidence. Read all three before proposing a fix.

### Step 3. Combine and Propose

Grounded advice needs both reads. The spec `message` says what the requirement wants. The `result.json` `message` and `metrics` say how this asset fell short. State both, then propose the fix:

- Name the requirement (`code`, feature `display_name`) and quote its spec `message`.
- State how the asset failed, citing the `result.json` `message` and the relevant `metrics` value.
- Propose the change to the USD asset that closes the gap.
- Tell the user where to apply it (their DCC tool or authoring pipeline) and that they re-run the test to confirm.

## Worked Example

The asset failed requirement `RB.COL.001` under feature `FET003`.

Step 1, the spec read. In the matching `config/*.json`, the `capability.requirements[]` entry with `code` `RB.COL.001` carries:

```json
{
  "code": "RB.COL.001",
  "name": "collision-api-present",
  "message": "Colliding Gprims must apply the Collision API.",
  "tags": "essential"
}
```

The capability `description` explains that the capability covers rigid-body collision behavior, and the `FET003` feature `display_name` is the feature name shown in the report.

Step 2, the failure read. The test's `result.json` `message` reads that no Gprim under the asset applies `UsdPhysicsCollisionAPI`, and `metrics` records `colliding_gprims_without_collision_api` with a value greater than zero.

Step 3, the proposal:

> Requirement `RB.COL.001` under the rigid-body feature requires that colliding Gprims apply the Collision API. This asset has one or more colliding Gprims with no Collision API applied, so the physics engine does not treat them as collidable. To fix this, apply `UsdPhysicsCollisionAPI` to each colliding mesh Gprim in the asset (in your DCC tool, this is usually the collision or physics setup on the mesh prim). After re-authoring, re-run the test to confirm `RB.COL.001` passes.

The proposal is concrete because the spec `message` is specific. Refer to the next section for what to do when it is not.

## Specific Versus Vague Requirement Messages

The quality of the advice follows the quality of the spec `message`.

When the `message` is specific (for example "Colliding Gprims must apply the Collision API."), give concrete USD-authoring steps as in the worked example.

When the `message` is terse or generic (for example "Physics behavior must be correct."), do not invent specifics the spec does not state. Instead:

- Say plainly that the requirement text is general.
- Pull in the capability `description` for additional context and quote the part that bears on the failure.
- Combine that context with the `result.json` `message` and `metrics` to give the best-grounded general guidance you can, and name the measurement the user should drive in the right direction.
- Point the user at the requirement's `code` and feature `display_name` so they can consult the spec author or the project's requirement documentation for the precise intent.

Honest, bounded guidance beats a confident guess.

## Key Rules

- Bounded scope. This skill explains what a requirement wants and proposes how to fix the USD asset. It does not auto-edit the user's asset. Remediation is advice the user applies in their own DCC tool or pipeline, after which they re-run the test.
- The original asset directory is never modified by the framework, and this skill holds to the same invariant. The framework writes only to the output directory (mirror copies under `results/`).
- Ground every claim in two reads. State the spec requirement `message` and the asset-specific `result.json` `message` and `metrics` together. Advice that cites only one of the two is not grounded.
- Consult the user's actual sr_specs, not general knowledge. Requirement messages are authored per project.
- Do not invent requirement codes, messages, or thresholds. When the spec is vague, say so and give general guidance with a pointer to the capability `description`.

For the sr_specs directory structure and field shapes refer to [references/sr-specs-lookup.md](references/sr-specs-lookup.md).
For finding which requirements failed refer to the [diagnose-failures](../diagnose-failures/SKILL.md) skill.
