skore-physics-low-repro

name	skore-physics-low-repro
description	Turn rare physics failures into deterministic unattended repro captures with seeded runs, targeted predicates, and snapshot logs.

skore-physics-low-repro

Purpose

Use this skill whenever a physics issue is rare, timing-sensitive, seed-sensitive, or difficult to reproduce by hand.

The goal is to convert "I saw an impossible physics state once" into:

1. a deterministic launch command,
2. an unattended detector,
3. a scene snapshot or hit log with enough state to replay and debug,
4. minimal manual input while the loop runs.

The current edge-rest work is a deterministic seeded scene plus debug snapshot workflow. Treat a dedicated unattended detector as the next step only when the scene and launcher snapshots are not enough.

Generic Capture Pattern

For any low-repro physics bug:

1. Define the impossible state as a precise predicate.
2. First try to make a deterministic scene and seed that reproduces it.
3. If a scene is not enough, add a command-line capture mode, usually --<problem>-test [log_path].
4. Write the log header before the simulation loop starts.
5. Disable normal interactive input during the unattended run unless the repro requires input.
6. Scan every frame after physics has advanced.
7. On first hit, write a full snapshot and stop the app.
8. Include a replay command hint with seed, renderer, scene, object mode, time scale, fixed-step state, and important feature toggles.

Keep the detector narrow enough to avoid false positives, but log enough context to refine it later.

Required Log Contract

Every low-repro capture log should include:

• log path and start timestamp,
• renderer,
• scene path or generated-scene marker,
• RNG seed and command-line seed override,
• fixed-step state and time scale,
• relevant runtime toggles (--no-water, object-generation overrides),
• model count and selected model index,
• position, velocity, angular velocity, orientation, mass, restitution, inertia,
• collision shape details,
• sleep state and sleep-support state when relevant,
• terrain/sample data when terrain contact is relevant,
• contact/manifold data when object contact is relevant,
• detector-specific fields,
• a replay command hint.

Prefer reusing the same snapshot payload used by launcher-mode repro logging so manual and unattended captures produce comparable artifacts.

Detector Design

A good detector usually answers four questions:

1. What object type or body set can fail?
2. What physical invariant is violated?
3. What nearby supports or contacts explain the state?
4. What conditions should exclude normal, physically valid cases?

Examples:

• Floating body: not sleeping, below speed threshold, no terrain/object contact, positive terrain gap.
• Impossible rest state: awake body, near-zero velocity, no support contacts.
• Penetration: contact manifold reports penetration above tolerance after solver step.
• Energy spike: total kinetic/potential energy increases above tolerance in a no-energy-source scene.
• Edge-rest box: awake box, low motion, only one or two terrain-supported vertices, no box-box contacts.

Runbook

1. Build the target configuration. Use Profile for fast visual repro runs, or Debug when you need launcher snapshot output:

tools\validate_build.bat Profile
tools\validate_build.bat Debug

2. Start the capture command from the repo root:

Profile\SKULLBONEZ_CORE.exe --scene SkullbonezData/scenes/standing_box_repro.scene.json --seed 4096348761 --no-water

3. When a snapshot is needed, rerun the same command with Debug\SKULLBONEZ_CORE.exe, enter launcher mode, and press Enter on the suspicious object to append to Debug\launcher_repro_snapshots.txt.
4. Use the logged replay command and snapshot fields to debug in Debug or under CDB.

If a future detector writes a log, preserve hit artifacts before rerunning the same path.

Current Example: Edge-Rest Box

Example command:

Profile\SKULLBONEZ_CORE.exe --scene SkullbonezData/scenes/standing_box_repro.scene.json --no-water --seed 4096348761

Edge-rest predicate used for manual review and any future detector:

• target is a box,
• target is not sleeping,
• speed squared is below 0.25,
• angular speed squared is below 0.09,
• terrain support count is 1..2 vertices,
• no contact manifold against any other box.

Known hit from the first capture:

• seed: 4096348761
• model index: 38
• supported vertices: 2
• min terrain gap: 0.042717
• max terrain gap: 3.013268
• sleeping: 0

The important lesson from this example is not the box-specific predicate. It is the reusable workflow: predicate, seed, scene or unattended loop, snapshot, stop-on-hit when a detector exists, and replay.

Validation

Documentation-only changes require no validation.

For new or changed detector code that touches SkullbonezRun* or physics behavior, use the cumulative focused pre-commit/PR validation required by AGENTS.md. Do not run the terminal full-plan gate for an ordinary detector commit.

tools\validate_fast.bat
tools\validate_physics.bat