Debug instability
Workflow
- Goal
- the cause of a Steel scene's misbehavior (explosion, jitter, sinking, tunnelling, slipping grasp, open loop, overflow, NaN), and the smallest change that removes it.
- Use when
- a scene misbehaves under Steel, a trial or autotune ends unhealthy, a render grades unstable, or a ported task diverges from PhysX.
- Done when
- the cause is named with evidence, the fix passes the scene's gates over the whole task, or the report says why no setting can fix it.
Any coding agent, or a person, can follow this workflow from agents/workflows/debug-instability/README.md. Tools that discover skill folders also find it assteel-debug-instability.
Inputs. The scene and the settings that misbehave; when it goes wrong (time, frame, load); a trial or a render of it if you have one.
Steps
-
run-trial at the failing settings. Read the advice in order: the first fix is the one to make first; later numbers are unreliable until it is made.
-
Decide by the first problem:
First problem Next dropped rows ( *_), contact buffer fullcapacity size-capacities, then step 1 again start state written to body_/q body_onlyqd change the example: write joint_/q joint_and run FKqd shapes overlapping at rest add collision-filter pairs in the example non-finite contact geometry report it with the shapes and frame from trial.; check the shapes’ geometryjson authored limits off, open loop, sinking heavy-on-light, grasp slip, warm-start bursts apply the advice’s fix with tune-one-knob; the guide’s section 4 recipe for that case failed check, no rule fired tune-one-knob: double substeps, then iterations a body vanished, nothing flagged render-and-grade and visual-review before calling it lost differs from PhysX only check-parity -
Re-run the whole task with the change and confirm the problem is gone and nothing else got worse (the same gates as before, plus the frames).
-
If the scene still fails at 32 substeps and 48 iterations, stop changing settings: it is a scene or solver problem. Write down the smallest reproduction (scene, settings, frame, the trial’s evidence).
Deliverables
The cause, the evidence (trial facts, frames, traces), the fix and its cost, or the reproduction for a scene or solver problem.
Steps it uses
- Run a trial runs one example's whole episode with Steel at given settings and lists what is wrong, in fix order.
- Size capacities sets Steel's constraint-row capacities so no row is ever dropped, with headroom, from measured demand.
- Tune one knob changes a single setting, holding everything else fixed, and keeps it only if every gate still passes.
- Render and grade renders examples with their Steel presets on one or more GPUs, records stability metrics, and grades each scene ok, suspect, unstable or failed.
- Visual review looks at frames across each episode and records a grade and a note per scene the metrics may have misjudged.
- Check parity compares two traces of the same task step by step by name, and audits each difference down to a cause.
Source: agents/workflows/debug-instability/README.md, the copy agents read.
Steel docs and tutorials are licensed under Apache-2.0. Third-party notices. "Skild", "Skild AI" and the Skild logo are trademarks of Skild AI and are not licensed under Apache-2.0.