# sr_specs Lookup Reference

This reference describes the layout of the user's sr_specs directory and how to find a failed requirement so the [remediate-assets](../SKILL.md) skill can read what a requirement wants. Field paths and directory candidates are verified against `simready_benchmark/reporter/specs_reference.py` and `simready_benchmark/core/specs_loader.py`.

Find the sr_specs path with `simready-benchmark --show-config`, which prints the resolved `sr_specs` source.

## Directory Layout

sr_specs ships three kinds of content the framework reads. Each has two accepted locations, and the framework takes the first one that exists.

| Content | Primary location | Alternate location |
|---|---|---|
| Capabilities and requirements | `config/*.json` | (only `config/`) |
| Feature definitions | `features/*.json` | `docs/features/*.json` |
| Profiles | `profiles.toml` | `docs/profiles/profiles.toml` |

For remediation, the two reads that matter are the requirement (`config/*.json`) and the feature display name (`features/` or `docs/features/`). The profiles file maps profiles to features and is not needed to remediate a single requirement.

## Capabilities and Requirements in config

Each file under `config/` holds one `capability` object. The framework reads it through `build_specs_reference` in `reporter/specs_reference.py`.

```json
{
  "capability": {
    "id": "physics-rigid-bodies",
    "name": "Physics Rigid Bodies",
    "description": "This capability enables rigid-body collision behavior...",
    "requirements": [
      {
        "code": "RB.COL.001",
        "name": "collision-api-present",
        "message": "Colliding Gprims must apply the Collision API.",
        "tags": "essential"
      }
    ]
  }
}
```

Field paths the skill reads:

| Field path | Use in remediation |
|---|---|
| `capability.id` | Capability identifier. |
| `capability.name` | Human-readable capability name. |
| `capability.description` | Broader context for what the capability is for. Use this when a requirement `message` is terse. |
| `capability.requirements[]` | The list to search by `code`. |
| `capability.requirements[].code` | The requirement code to match, for example `RB.COL.001`. |
| `capability.requirements[].name` | Requirement slug, for example `collision-api-present`. |
| `capability.requirements[].message` | The human-readable requirement text. The primary read for remediation. |
| `capability.requirements[].tags` | Severity or grouping, for example `essential`. |

A file whose top-level object has no `capability` key is skipped by the framework.

## Finding a Requirement by Code

The requirement `code` is unique across all `config/*.json` files (the framework keys its requirements dict by `code`). To find a failed requirement:

1. Walk every `*.json` file under the `config/` directory.
2. In each file, read `capability.requirements[]`.
3. Find the entry whose `code` equals the failed requirement code.
4. Read that entry's `message`, `name`, and `tags`, and the surrounding `capability.description`.

If no entry matches the code, the code is not defined in this sr_specs. Tell the user the code was not found rather than guessing what it means.

## Feature Definitions in features

Feature files live under `features/` or `docs/features/`. The framework reads them through both `specs_reference.py` and `specs_loader.py`.

```json
{
  "id": "FET003",
  "display_name": "Rigid Body Dynamics",
  "version": "1.0",
  "requirements": ["RB.COL.001", "RB.MASS.001"]
}
```

Field paths the skill reads:

| Field path | Use in remediation |
|---|---|
| `id` | Feature identifier, for example `FET003`. Match the feature the failing test covers. |
| `display_name` | The feature name shown in the report. Name this in the advice. Falls back to `id` when absent. |
| `version` | Feature version. |
| `requirements[]` | The requirement codes this feature includes. |

When more than one feature file shares an `id` (multiple version files), the framework keeps the entry with the most `requirements`.

## profiles.toml

The profiles file maps each profile and version to its feature set. It is read by `load_profiles` in `specs_loader.py` and lives at `profiles.toml` or `docs/profiles/profiles.toml`. Single-requirement remediation does not need it, so it is listed here only for completeness of the sr_specs layout.

```toml
[Prop-Robotics-PhysX.1_0]
features = [
    { FET003 = { version = "1.0" } },
]
```

## Fields Available for Remediation

Combine these into a fix proposal:

| Source | Field | Role |
|---|---|---|
| `config/*.json` | `capability.requirements[].message` | What the requirement wants (human-readable). |
| `config/*.json` | `capability.description` | Context when the `message` is terse. |
| `config/*.json` | `capability.requirements[].tags` | Severity of the requirement. |
| `features/*.json` | `display_name` | The feature name to cite. |

Pair these with the asset-specific `message` and `metrics` from the per-test `result.json`. The combine step is described in the [remediate-assets](../SKILL.md) skill.
