/cs-dl-diagnose

name: "cs-dl-diagnose"
description: "/cs:dl-diagnose — Diagnose a training run against Chapter 11's decision tree: read training error before deciding anything, and never diagnose a NaN as overfitting. Returns a ranked cause, the specific next action, and the chapter that justifies it."
argument-hint: "[what the run is doing — losses, gradient norm, or a description]"

/cs:dl-diagnose — Measurement first, hypothesis second

**Command:** `/cs:dl-diagnose [symptoms]`

Chapter 11's rule, which most teams have backwards: **read training error first.** High training error means the model or the optimizer is the bottleneck, and more data cannot help.

Procedure

1. **Collect the instruments.** Ask for what is missing, in this order:

• training loss and validation loss (same units, same epoch)
• the target loss — a human baseline, a published number, or an irreducible-error estimate

(without it, underfitting cannot be distinguished from convergence)

• global gradient norm, if available
• has the loss ever gone NaN or inf?
• can the model drive training loss to ~0 on 10–50 examples? (the smoke test that separates

a bug from a hard problem) 2. **Run the tool:**

   python3 engineering/deep-learning-book/skills/deep-learning-book/scripts/training_diagnostics.py \
       --train-loss <x> --val-loss <y> --target-loss <z> --grad-norm <g> \
       --tiny-subset-fits yes|no|unknown

Exit 4 means not enough instruments — ask for one of the named measurements rather than guessing. 3. **Act on finding [1] first.** Rules fire in priority order for a reason: a non-finite loss is a numerics failure, not a modelling one, and a model that cannot overfit 20 examples has a bug that no hyperparameter will fix. 4. **On an OVERFIT verdict**, follow up with the capacity planner, which ranks the regularization ladder and applies the double-descent correction:

   python3 .../capacity_planner.py --params <n> --train-examples <m> \
       --train-error <x> --val-error <y> --applied early-stopping

5. **On a memory or throughput question**, run `model_arithmetic.py --spec <file>` — it reports parameters, FLOPs and activation memory per example, and refuses a stack whose shapes do not connect. 6. **Close with the discipline, not just the fix:** change one thing per experiment, log it, re-measure the gap.

Do not

• Skip to the interesting hypothesis before the rules have been read in order.
• Recommend collecting data while training error is high.
• Recommend shrinking an overparameterized model first — see the double-descent caveat in

`skills/deep-learning-book/references/book_to_2026_delta.md`.