---

name: checkpoints-and-diagnostics description: "Inspects and troubleshoots MuZero General checkpoints, replay buffers, TensorBoard artifacts, and model-dynamics diagnostics." disable-model-invocation: true metadata: disco-role: operating license: MIT

Checkpoints and Diagnostics

Use this sub-skill when the task is to load or inspect model.checkpoint, reason about replay_buffer.pkl, avoid checkpoint/config mismatches, understand results/<game>/<timestamp>/, run non-interactive diagnostics, or troubleshoot Graphviz/matplotlib/TensorBoard artifacts.

Fast route

1. Read checkpoints-and-diagnostics.md for checkpoint schema, save/load paths, replay buffer fields, DiagnoseModel methods, TensorBoard artifacts, and safe headless workflows.

2. Read troubleshooting.md when paths are invalid, torch.load fails, weights do not match the selected config/network, replay buffer loading fails, Graphviz is missing, or plotting blocks a headless session.

3. Inspect a checkpoint without running a model:

   python sub-skills/checkpoints-and-diagnostics/scripts/inspect_checkpoint.py --checkpoint <model.checkpoint> --json
   

4. Before calling MuZero.load_model(...), confirm the intended game/config in games-and-configs and model shape compatibility in models-and-mcts.

Scope and routing boundaries

This sub-skill owns:

• MuZero.load_model(checkpoint_path=None, replay_buffer_path=None) behavior.
• SharedStorage.save_checkpoint(path=None) and default model.checkpoint paths.
• Checkpoint dict keys, counters, weight state dicts, optimizer state, and replay buffer pickle metadata.
• DiagnoseModel and Trajectoryinfo usage boundaries.
• Optional Graphviz and plotting dependencies.
• Safe non-interactive checkpoint inspection and headless diagnostic planning.

Route elsewhere when the task is primarily about:

• Producing checkpoints through training, TensorBoard logging loop, or CLI commands: training-and-cli.
• Choosing game/config fields for checkpoint compatibility: games-and-configs.
• Interpreting network tensor shape, support size, or MCTS internals: models-and-mcts.

Safe defaults

• Use torch.load(..., map_location="cpu") for inspection unless the user explicitly wants GPU loading.
• Do not bundle or depend on source results/ binary checkpoints; they are evidence of schema and naming only.
• Do not call MuZero.diagnose_model in automation; it calls plotting paths and then waits for input.
• Prefer DiagnoseModel(...).compare_virtual_with_real_trajectories(..., plot=False) only after a matching config/game/checkpoint is loaded and a real observation is available.

Compatibility checklist

Before loading a checkpoint for testing or diagnostics:

• Game module matches the checkpoint's architecture assumptions.
• network, support_size, observation_shape, action_space, stacked_observations, channels/encoding_size, and downsample fields match the saved weights.
• Replay buffer, if loaded, was produced by the same or compatible game/config.
• Paths point to files, not directories.
• Optional plotting dependencies are installed only when plots are needed.