Debug solving errors
Find the failure mechanism and validate a repair against the original scenarios.
Use
for model edits and
for trial mechanics. Preserve
source revisions and perform experiments on copies within the authorized scope.
PREREQUISITE: This skill needs an initialized
connection and
an SDK satisfying its
range. Run the
skill (
../jinko-sdk-setup/SKILL.md
) and proceed only once its check passes.
Use
when it is set. Otherwise, obtain a fresh session code
before this skill's SDK process, as instructed by the setup skill.
Also check that
python -m jinko.cli.debug_solving --help
works. If the
command is missing, upgrade
. Do not replace the command with
private transport calls.
Collect before changing
Run the deterministic diagnostic command into a new directory. It does not edit
items or start trials. A model solve requires
explicitly.
bash
python -m jinko.cli.debug_solving --model-sid cm-... --out debug/model
python -m jinko.cli.debug_solving --trial-sid tr-... --revision 2 \
--telemetry --out debug/trial
For one authorized model probe, select representative outputs and preserve exact
formula overrides in a JSON object. The command uses at most ten output slots.
Available telemetry fills remaining slots; absent metrics are reported as such.
bash
python -m jinko.cli.debug_solving --model-sid cm-... --revision 4 \
--run-simple-solve --timeseries-id Time --timeseries-id Drug \
--overrides-json case.json --telemetry --out debug/probe
Use
to retain an exact patient row from the bound population;
this reads the population. The bundle also records the bound protocol and trial
options. Reconstruct the scenario from all three. Do not assume the model head,
its default settings, or a bare patient row represents the failed trial arm.
limits telemetry downloads, not the original failure inventory.
Read
and collection errors before interpreting the bundle. Exit
codes are 0 for successful collection without detected failure, 1 for a reported
model/solve/patient failure, and 2 for incomplete collection or invalid input.
Neither exit 0 nor finite outputs establish numerical or scientific validity.
Choose the investigation
- Slow or timed out: separate client wall time, solver time, compilation,
and incomplete evidence. Treat at least 15 seconds as a configurable signal.
Inspect the solver, tolerances, state scales, maximum step, and auxiliary
events before choosing a bounded experiment.
- Patient/arm subset: group raw errors by patient and arm, compare exact
inputs with a successful control, and retain the full failure set. Shared
derivative names can conceal different upstream causes.
- Non-finite derivative: trace upstream expressions, including division,
logarithms, roots, fractional powers, and switched branches. The reported
derivative is not necessarily the first invalid expression. The reported
last solved time may be an earlier output point.
- Setup or export error: inspect trial-context sanity, formulaic descriptor
overrides, unit mode, and event schedule. Keep unit/conversion defects separate
from runtime defects. For failed exports, preserve the error and use native
JSON plus options when supported.
Read investigation guidance for telemetry meaning,
controlled solver experiments, and independent replication after a full timeout.
Verify and report
Change one cause at a time. Compare the original failing case, a successful
control, and then all original subjects and arms. Check finite trajectories,
physiological constraints, event behavior, and numerical sensitivity. Halve the
maximum step or tighten tolerances for a justified comparison; do not call an
unconverged candidate validated merely because every subject completes.
Report evidence, hypotheses, copy-level changes, remaining failures, and open
scientific questions separately. Record pins, settings, override warnings,
metrics, and comparison tolerances. Never silently drop failing patients, loosen
accuracy to obtain completion, or apply a model-specific clamp to other models.