# Debug ML Training Failures

ML training can fail through NaN loss, overfitting, slow convergence, or unstable gradients. This skill guides diagnosis, targeted fixes, validation, and reporting.

## Install

```bash
npx skillstore add dnyoussef/when-debugging-ml-training-use-ml-training-debugger
```

## Metadata

- Status: approved
- Slug: dnyoussef-when-debugging-ml-training-use-ml-training-debugger
- Version: 1.0.0
- Author version: 1.0.0
- Skillstore revision: r1
- Version status: valid
- Tree hash: 2feea8a02af031956ecb16da49b05a6c92f5a2c5646ccd3845f2140bb88153fc
- Author: DNYoussef
- GitHub username: DNYoussef
- License: MIT
- Repository: https://github.com/DNYoussef/ai-chrome-extension/tree/main/.claude/skills/machine-learning/when-debugging-ml-training-use-ml-training-debugger
- Ref: c579efd02184f1128d6741d16e6c8d951d7d4208
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: external\_commands, filesystem
- Quality score: 80
- Quality tier: silver
- Public page: https://skillstore.pages.dev/skills/dnyoussef-when-debugging-ml-training-use-ml-training-debugger
- Manifest: https://skillstore.pages.dev/api/skills/dnyoussef-when-debugging-ml-training-use-ml-training-debugger/manifest

## Capabilities

- Diagnoses loss divergence, NaN loss, overfitting, slow convergence, and gradient issues.
- Guides training history analysis using loss and validation metrics.
- Suggests fixes such as learning rate changes, dropout, L2 regularization, and gradient clipping.
- Compares before and after training metrics to validate improvements.
- Generates diagnostic and optimization reports for ML training runs.

## Use Cases

- Diagnose Unstable Training: Find likely causes when loss becomes NaN, infinite, or sharply increasing during training.
- Reduce Overfitting: Compare train and validation curves, then select regularization or data changes.
- Validate Training Fixes: Retrain with selected fixes and compare before and after performance metrics.

## Prompt Templates

### Diagnose Training History

```
Use this skill to review my training history and identify the most likely cause of unstable loss.
```

### Investigate Overfitting

```
Use this skill to compare training and validation curves, then recommend regularization changes for overfitting.
```

### Validate a Fix

```
Use this skill to apply one selected training fix, retrain the model, and compare before and after metrics.
```

### Optimize a Production Run

```
Use this skill to analyze gradients, data quality, architecture, and before-and-after metrics for a slow production training run.
```

## Limitations

- Requires existing training history, model objects, and datasets in the user workspace.
- Examples assume TensorFlow or Keras patterns and may need adaptation for PyTorch.
- Does not guarantee improved model accuracy on poor or biased datasets.
- May retrain models, which can consume compute time and resources.

## Best Practices

- Review generated fixes before retraining on expensive hardware.
- Keep original model checkpoints and training history for comparison.
- Run changes on a small dataset subset before a full training run.

## Anti Patterns

- Running every suggested fix without confirming the root cause.
- Overwriting previous training artifacts without saving a baseline.
- Treating validation improvement as production readiness without external evaluation.

## Security Audit

- Audited at: 2026-07-05T12:29:20.341\+00:00
- Summary: AI review found the external command findings are false positives caused by Markdown code fences and template literals in examples. The filesystem findings are fixed local output writes for diagnostic artifacts, and no prompt injection, exfiltration, or malicious command intent was found.

## Stats

- Views: 196
- Downloads: 4
- Favorites: 0
- Popularity score: 0