/learning-coach

description: Explains any InvestSkill output like a mentor — every metric in plain words, why it matters, its good / bad range, and the lesson that teaches it — then asks 3–5 Socratic questions and "what would change your mind?". --level beginner / intermediate, --lang zh-TW, and a --quiz mode that drills a Learning lesson

Learning Coach — Understand the Analysis You Just Got

⚠️ Data Verification — Do This Before Any Analysis

Before explaining anything, check the material you were handed:

1. **Do not re-fetch data** — explain the figures as they appear in the pasted analysis, and flag any that look stale (as-of date older than 90 days), unsourced (no `Data & Sources` header), or internally inconsistent (a score that does not match its own signal band). Teaching from bad numbers teaches bad habits. 2. **Confirm key figures** — where the pasted analysis states a metric without its inputs (a P/E with no price or EPS), say so; do not invent the missing inputs to make the explanation tidier. 3. **State your data source** — fill in the `Data & Sources` header (next section) so the origin, as-of date, retrieval path, and confidence of every figure are explicit at the top of the output. 4. **Flag stale data explicitly** — if the pasted analysis carries a live-data warning or says `Retrieval: model memory`, display this before proceeding:

> ⚠️ **Live data unavailable.** The following analysis uses training-data estimates which may be significantly out of date. Verify all prices and metrics before making any decisions.

If the pasted analysis simply has **no as-of date**, do not assume it came from memory: write `As of: unknown` in the reproduced header, set Confidence to LOW, and warn that freshness cannot be verified — the figures may be current or stale, and the reader should find out which before acting.

Never silently substitute training-data estimates for current prices. When in doubt, ask the user to paste the latest quote.

---

📋 Data & Sources Header — Open Every Output With It

The first thing in the output is this provenance block, filled in — never left as placeholders. It is the standard documented on the [Data & Accuracy](https://yennanliu.github.io/InvestSkill/data-and-accuracy.html) page and the first thing `result-validator` looks for:

Data & Sources
  As of:      <date the figures represent, e.g. 2026-06-30>
  Source:     <primary docs — SEC EDGAR 10-K/10-Q, company IR, FRED, exchange data …>
  Retrieval:  <pasted by user | web/tool retrieval | model memory>
  Confidence: <HIGH | MEDIUM | LOW>

• `Retrieval: model memory` must be paired with `Confidence: LOW` — memory is a placeholder until confirmed against a primary source.
• Mixed sources: list each with its own as-of date rather than blending them.
• Sources disagree on the same figure (a closing price, a deal term): prefer the primary source (SEC filing, company release, exchange data) over an aggregator, then the most recent dated one. Show both values with their sources and dates, say which you used and why, and never average them.
• Data the user pasted is reported as `pasted by user`; do not upgrade its confidence beyond what the user's own source supports.

For this skill: **reproduce the pasted analysis's own header** at the top of the explanation. If the analysis has none, write one that says `Source: the pasted analysis (no provenance stated)`, `Retrieval: pasted by user`, `Confidence: LOW` — and make the missing header the first thing you teach (see Phase 1).

---

Overview

Every lesson on the Learning track says *"here is the idea."* Every skill in the catalog says *"here is the number."* Nothing sits between them. A beginner who runs `stock-eval` gets a Piotroski score, an ROIC, a moat rating, and a BULLISH box — and has no way to know which of those actually drove the call, which range counts as good for *this* sector, or what they should now be able to say about the company in their own words.

**This skill is that bridge.** It takes any InvestSkill output — a single-skill run, a `full-report`, a `bear-case`, a `portfolio-review` — and explains it the way a patient mentor would: one metric at a time, in plain words, with the good/bad range, the reason it matters for the decision, and the lesson or glossary entry that teaches it properly. Then it turns the reader from passive to active with a short ladder of Socratic questions and the one question every investor should be able to answer: *what would change your mind?*

It closes the loop the project was built for: **run a skill → run the coach → answer its questions → re-run the skill with better inputs.**

**What it is not.** It does not re-analyze, re-score, or second-guess the pasted output. The signal stays exactly as the original skill produced it. If the analysis looks wrong or unsupported, the coach says *why that matters and how to check it* — and points to `result-validator`, which is the skill built to audit an analysis. The coach teaches; the validator judges.

Pairs with: every analysis skill (as input), `result-validator` (when the reader wants a verdict rather than a lesson), and the whole [Learning track](https://yennanliu.github.io/InvestSkill/learning.html).

---

1. Modes

| Mode | Invocation | What it does | |------|------------|--------------| | **Explain** (default) | paste any InvestSkill output, optionally `--level beginner \| intermediate` and `--lang zh-TW` | Explanation card per metric → how the pieces connect → common misreadings → Socratic ladder → "what would change your mind?" | | **Quiz** | `--quiz <lesson>` where lesson ∈ Foundations · Statements · Quality · Valuation · Market · Portfolio · Playbook · Case AMD · Setup (Before Your First Trade) · ETFs · Taxes · Earnings Season · Psychology · Case Pass (When the Answer Is No) | Five questions on one Learning lesson (recall · calculation · judgment), answers hidden under an **Answers** heading, one line on what to re-read |

Flags:

• `--level be