# Simulation Failure Triage

> Triage cross-code simulation failures and propose safe retry ladders for nonconvergence, NaN/Inf, exploding energies, unstable timesteps, pressure blow-up, missing potentials, bad pseudopotentials, corrupted output, and incomplete runs. Use when an agent sees a failed or suspicious materials simulation and needs a defensible first response.

- Skill: `zuoguyoupan2023/simulation-failure-triage` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zuoguyoupan2023/simulation-failure-triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zuoguyoupan2023/simulation-failure-triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zuoguyoupan2023 (https://skillmd.com/u/zuoguyoupan2023)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zuoguyoupan2023/simulation-failure-triage

---


# Simulation Failure Triage

## Goal

Classify common simulation failure signatures and return immediate actions, retry ladders, and stop conditions.

## Requirements

- Python 3.10+
- No external dependencies
- Works on Linux, macOS, and Windows

## Inputs to Gather

| Input | Description | Example |
|-------|-------------|---------|
| Code | Simulation code | `LAMMPS`, `VASP`, `MOOSE`, `QE` |
| Stage | Setup, runtime, postprocess | `runtime` |
| Symptoms | Failure signs | `nan,pressure-blowup` |
| Log text or file | Error evidence | `Lost atoms`, `ZBRENT` |
| Recent change | Last modified setting | `larger timestep` |

## Decision Guidance

- First preserve evidence: logs, inputs, executable version, and scheduler output.
- Separate setup errors from numerical instability and physical model issues.
- Retry with a single controlled change.
- Stop retrying when the result becomes scientifically meaningless or a required model input is missing.

## Script Outputs

`scripts/failure_triage.py` emits:

- `likely_causes`
- `immediate_actions`
- `retry_ladder`
- `stop_conditions`
- `evidence`

## Workflow

```bash
python3 skills/robustness/simulation-failure-triage/scripts/failure_triage.py \
  --code LAMMPS \
  --stage runtime \
  --symptoms nan,pressure-blowup \
  --recent-change "increased timestep" \
  --json
```

## Error Handling

Invalid stages or oversized log files stop with exit code 2. Unknown symptoms are retained as custom evidence.

## Limitations

This skill gives first-response triage. It does not guarantee that a failed simulation can be repaired.

## Security

- Log files are read with a 10 MB size cap.
- Log text is truncated and never executed.
- The script does not run external solvers.
- The skill uses `Bash` only to run its bundled script.

## References

- See `references/failure_patterns.md` for common failure signatures and retry ladders.

## Version History

- 1.0.0: Initial cross-code simulation failure triage skill.