Explain Results

Explain Results

Translates YOLO training metrics into plain-English explanations. Two audience modes: non-technical (default) and technical.

Data

Find the experiment to explain:

1. If user specifies a path or experiment ID, use that
2. Otherwise, find the latest experiments/exp_NNN_* directory (highest NNN)

Read from the experiment directory:

• report.md — experiment summary with metrics and deltas
• metrics.yaml — structured metrics, per-class AP, overrides, config
• train/results.csv or results.csv (if available) — epoch-by-epoch training log

Also read:

• experiments/summary.md — for historical context (how this compares to other runs)
• experiments/dataset_profile.yaml — for dataset size, class counts, image counts
• Reference thresholds from skills/analyze-results/resources/metrics-guide.md

Report Structure

Generate a plain-English report with these sections:

1. What Happened

Summarize the training run in one paragraph a project manager could understand.

Template: "We trained a [model] for [X epochs] on [Y images] across [Z classes]. The training [completed normally / stopped early at epoch N / showed signs of overfitting]. This took approximately [time if available]."

Include what changed vs baseline if this is not the baseline run (e.g., "This run increased the image size from 640 to 1280 pixels").

2. How Good Is It

Translate the core metrics using analogies, not jargon. Use the metrics-guide.md thresholds to provide context.

| Quality | mAP50-95 | Plain English | |---------|----------|---------------| | Great | >0.60 | "The model reliably finds and precisely locates objects — ready for production use" | | Good | 0.45-0.60| "The model catches most objects and places boxes reasonably well — solid for many applications" | | Fair | 0.30-0.45| "The model finds some objects but often misses or misplaces them — needs more work" | | Poor | "correctly identifies the object 85 out of 100 times it makes a detection")

• Recall: "Out of all the objects actually present, the model finds X%" (e.g., recall=0.70 -> "catches 70 out of every 100 objects in the images")
• mAP50: "How well it draws boxes around objects (at a forgiving threshold)" — use this to explain detection quality
• mAP50-95: "The overall score — combines finding objects AND precisely outlining them"

If there is a baseline comparison, translate the delta: "Compared to our starting point, this run [improved/decreased] overall detection by [X points]. In practical terms, [concrete impact]."

3. What It's Best At

List the top-performing classes by per-class AP (from metrics.yaml per_class_ap).

Use plain language: "The model is strongest at detecting [class] — it correctly finds and outlines [X]% of them."

Group into tiers using metrics-guide.md per-class thresholds:

• Nailed it (AP > 0.80): These classes are well-learned
• Getting there (AP 0.60-0.80): Decent but room to improve
• Needs work (AP 0.40-0.60): Struggling — likely needs more training data
• Not yet (AP .md`.

Guidelines

• Keep it practical — no AI hype, no buzzwords
• Use "the model" not "the AI" or "the neural network"
• Percentages and fractions over decimal scores: "85 out of 100" not "0.85"
• Frame struggles as opportunities: "needs more examples" not "fails at"
• When in doubt, explain less and recommend more
• Always ground quality judgments in the metrics-guide.md thresholds — don't invent your own scale
• If data is missing (no results.csv, no per-class AP), say so plainly and skip that section rather than guessing

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MacroMan5
• Source: MacroMan5/autotrain-yolo
• License: MIT

Install and usage instructions live in the source repository linked above.