debug-ml-research

Diagnose silent failures in ML experiments where runs complete but results are wrong.

Updated Jul 3, 2026
One-click install
npx skills add https://github.com/mnazaal/dotfiles --skill debug-ml-research-mnazaal
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debug-ml-research
Source: https://github.com/mnazaal/dotfiles/tree/main/.agents/skills/debug-ml-research
Command: npx skills add https://github.com/mnazaal/dotfiles --skill debug-ml-research-mnazaal

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? ML experiments often run without errors yet produce wrong or misleading results: a metric that looks too good, a number that moved when nothing changed, or a mechanism asserted but never measured. This Skill provides a systematic diagnostic ladder and targeted probes to find the real cause instead of trusting plausible-looking logs. ## Core Features & Use Cases - Diagnostic Ladder: A seven-step progression from verifying the objective and data meaning through tiny overfitting, synthetic recovery, eval consistency, and baseline comparison. - Strip-to-Boring Protocol: Reduce to one seed, one device, one batch, and remove augmentation, dropout, distributed training, mixed precision, and EMA to isolate the bug. - Specialized Probes: Checks for probabilistic models, diffusion conventions, latent-component identifiability, seed sweeps, invariance sweeps, and self-satisfying metrics. - Use Case: Your model recovers parameters on real data but a per-component metric fails on some seeds only. The Skill guides you to test label-permutation symmetry in the mixture model, add a component-distinguishing prior, and run multiple chains to confirm identifiability failure. ## Quick Start Ask the AI to debug why my ML experiment's metric improved unexpectedly even though nothing in the training setup should have changed.

Frequently Asked Questions about debug-ml-research

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug an ML experiment that runs without errors but gives wrong results?▼

Follow a diagnostic ladder: verify the model optimizes the intended objective, check data and target meaning, confirm the model can overfit a tiny dataset, validate on synthetic data with a known answer, and check that evaluation matches training. Strip the setup to one seed, one batch, and no augmentation first.

How to test if my model can overfit a small dataset?▼

Run a tiny overfit check by training on one example, then two, then one batch, then a fixed subset. If the model cannot drive the loss to near zero on a single example, the bug is in the objective, data pipeline, or gradient flow rather than in generalization.

Why does my metric pass after a fix I cannot explain?▼

A change that makes a metric pass without a derivable reason may work through an unrelated side-effect, such as accidentally breaking a symmetry, and mask the real bug. Treat unverified passing changes as suspect and derive what the corrected objective should imply before accepting the number.

When should I not use this debugging approach?▼

Do not use it for crashes or errors, which have a reproducible symptom and belong to root-cause debugging. It also does not apply to runs that are valid but merely disappointing, nor to building data pipelines before a bug has reached a run.

Why does my mixture model recovery fail on only some random seeds?▼

Mixture likelihoods are invariant to permuting component labels, so a single MCMC chain can lodge in one labeling and mis-split mass between components. Break the symmetry with a component-distinguishing prior, run multiple chains, or align labels post-hoc, and never conclude from one seed.