juce-random-effects-soak - SKILL.md Agent Skill

name: juce-random-effects-soak description: Run a full JUCE callback-path soak using 10 random native effects at once, rotating serial/parallel flow topologies and blend strategies between flows while collecting xrun, jitter, and CPU evidence. Use when validating engine stability after graph/device/lifecycle changes, reproducing post-start_audio regressions, or generating release-grade performance proof.

JUCE Random Effects Soak

Run the script in this skill to execute a long-duration JUCE soak with:

exactly 10 randomly selected effects active per flow epoch
rotating chain and parallel flow layouts
rotating blend behavior between flows
artifact capture for pass/fail evidence

Workflow

Build the JUCE engine module in Release mode.
Run a smoke soak first.
Run the full soak profile.
Review generated JSON and markdown evidence.

Commands

Smoke run:

python3 .codex/skills/juce-random-effects-soak/scripts/run_juce_random_fx_soak.py \
  --duration-seconds 180 \
  --flow-rotation-seconds 12 \
  --sample-interval-seconds 0.5 \
  --reset-stats-after-warmup

Full run:

python3 .codex/skills/juce-random-effects-soak/scripts/run_juce_random_fx_soak.py \
  --duration-seconds 1800 \
  --flow-rotation-seconds 20 \
  --sample-interval-seconds 1.0 \
  --reset-stats-after-warmup \
  --threshold-max-xruns 0 \
  --threshold-max-peak-jitter-ms 0.35 \
  --threshold-max-budget-utilization-percent 80

Device-targeted bench run (use the exact JUCE/JACK device name):

python3 .codex/skills/juce-random-effects-soak/scripts/run_juce_random_fx_soak.py \
  --audio-device "TASCAM US-144MKII Multichannel" \
  --duration-seconds 1800 \
  --flow-rotation-seconds 20 \
  --sample-interval-seconds 1.0 \
  --reset-stats-after-warmup \
  --threshold-max-xruns 0 \
  --threshold-max-peak-jitter-ms 0.35 \
  --threshold-max-budget-utilization-percent 80

Aggressive crash-repro variant (live rewire while callback is running):

python3 .codex/skills/juce-random-effects-soak/scripts/run_juce_random_fx_soak.py \
  --duration-seconds 600 \
  --flow-rotation-seconds 8 \
  --live-rewire

Required Outputs

JSON artifact with samples, flow transitions, selected effects, and checks
Markdown summary with PASS/FAIL verdict and thresholds
Stable callback behavior through repeated graph rewires

Default output path:

docs/fit-for-purpose-evidence/<YYYYMMDD>/juce-random-fx-soak-<timestamp>.{json,md}

Adjustment Rules

Keep 10 active effects per flow epoch.
Keep flow rotation enabled; do not run static topology for this skill.
Keep blend strategy rotation enabled between flow epochs.
Default to safe rewire mode (stop/start audio around graph rewires); enable --live-rewire only when intentionally probing race/crash behavior.
Use --reuse-effects only for focused callback-only triage where plugin load/unload churn is intentionally excluded.
Use --audio-device for bench evidence that must bind a specific interface. MAP2_SOAK_AUDIO_DEVICE is kept as an environment fallback for legacy runbooks, but the CLI flag is preferred because it is captured in the generated JSON/Markdown artifacts.

References

Flow and blend definitions: references/flow-and-blend-spec.md