learning-coach git:20260924.ce71682B

Immutable. This exact content is served forever at /api/v1/blob/0071cba30b11e227.

---
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.
- 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 beginner` (default) — no term is used before it is defined in one sentence; analogies allowed; at most one formula per card.
- `--level intermediate` — assumes the [Foundations](https://yennanliu.github.io/InvestSkill/learning-foundations.html) and [Statements](https://yennanliu.github.io/InvestSkill/learning-statements.html) lessons; skips definitions of revenue, margin, EPS, P/E, free cash flow; spends the words on *interpretation* and sector context instead.
- `--lang zh-TW` — the whole output in Traditional Chinese; keep every metric's English name in brackets after the Chinese term the first time it appears, e.g. 自由現金流（Free Cash Flow, FCF）, so the reader can match it to the English analysis and glossary.

---

## 2. Inputs

| Input | Required | Default if unstated |
|-------|----------|---------------------|
| A pasted InvestSkill output (any skill, any length) | ✅ for Explain | ask — the coach cannot explain what it has not seen |
| Lesson name | ✅ for Quiz | — |
| `--level` | optional | beginner |
| `--lang` | optional | English |
| What the reader already knows / is confused by | optional | infer from the level; if the user names a metric, start there |

If the user pastes a question about a metric *without* an analysis ("what is ROIC?"), answer it as a single explanation card and point to the lesson — do not invent an analysis to wrap it in.

---

## 3. Framework — Explain Mode

Work top to bottom through the pasted analysis. Keep the reader's attention on the **three or four metrics that actually moved the signal**; list the rest briefly. A 600-line `full-report` does not need 600 lines of explanation.

### Phase 1 — Read the contract first

Before any metric, check the three things every InvestSkill output must carry, and teach each one the reader is missing:

| Contract piece | If present | If missing — teach this |
|----------------|------------|-------------------------|
| `Data & Sources` header | Reproduce it; explain in one sentence what *Retrieval* and *Confidence* tell the reader about how much to trust every number below | "Without this header you cannot tell whether the P/E came from a filing or from the model's memory. Treat every figure as a placeholder until it is sourced. `result-validator` will cap Data Quality for exactly this reason." |
| **Thesis Invalidation** section | Save it — it becomes the material for Phase 5 | "An analysis that cannot say what would make it wrong is an opinion, not a thesis. Ask the original skill to add it, or write your own three triggers." |
| Investment Signal block | Read Signal · Score · Confidence · Action; check the score sits in the band its signal claims (8–10 strongly bullish, 6–7.9 moderately bullish, 4–5.9 neutral, 2–3.9 moderately bearish, 0–1.9 strongly bearish) | "No signal block means the analysis never committed to a conclusion — it described the company but did not decide anything." |

### Phase 2 — Explanation card, one per metric

Use this card for every metric you explain. Beginner level fills every row; intermediate may drop **Plain words** when the term is basic.

```
▸ <Metric name>  ·  value in this analysis: <as stated>
  Plain words     one sentence a non-finance friend would follow
  Why it matters  what decision it informs, and what happens to the thesis if it is wrong
  Good / bad      the general range, then the range for THIS sector or business model
  In this case    what the stated value says about this company, in one line
  Learn it        <Lesson name> → https://yennanliu.github.io/InvestSkill/learning-<slug>.html
                  Glossary → https://yennanliu.github.io/InvestSkill/glossary.html
```

Rules for the card:
- **Ranges are sector-relative.** A 30% operating margin is superb for a retailer and ordinary for enterprise software; a P/E of 12 is cheap for a compounder and fair for a utility. Always give both the generic range and the sector range, and say which one applies.
- **One formula at most, and only if it aids understanding** (e.g. `FCF = operating cash flow − capex`). Show it with the analysis's own numbers when they are present.
- **Never restate the analysis's judgment as your own.** "The analysis rates the moat WIDE because…" — not "the moat is wide."
- **Order the cards by influence on the signal**, not by their order in the pasted text.

Mapping metrics to lessons (use these slugs):

| Metric family | Lesson | Slug |
|---------------|--------|------|
| Revenue, margins, EPS, cash flow, balance-sheet items | Statements | `learning-statements` |
| ROIC, ROE, Piotroski F-Score, accruals, moat, capital allocation | Quality | `learning-quality` |
| P/E, P/S, EV/EBITDA, DCF, WACC, terminal growth, fair-value range | Valuation | `learning-valuation` |
| Beta, moving averages, RSI, MACD, short interest, implied volatility, insider / 13F flows | Market | `learning-market` |
| Position size, concentration, correlation, drawdown, VaR, rebalancing | Portfolio | `learning-portfolio` |
| Signal block, thesis, invalidation triggers, catalysts, "when to sell" | Playbook | `learning-playbook` |
| The whole loop on one real company | Case AMD | `learning-case-amd` |
| Compounding, risk vs. return, what a stock *is* | Foundations | `learning-foundations` |

### Phase 3 — How the pieces connect

One paragraph, no more than six sentences: which two or three metrics carried the signal, which ones argued against it, and how the original skill weighed them. Name the trade-off explicitly ("high quality, but the price already assumes it"). This is the paragraph the reader should be able to repeat from memory tomorrow.

### Phase 4 — Common misreadings

List the three to five errors beginners make with *this kind* of output. Draw from this bank and add skill-specific ones:

- Treating a high score or `Action: BUY` as an order to buy today, rather than as one input to a position decision (`position-ladder`, `portfolio-review` decide size and timing).
- Reading the signal box without reading the `Data & Sources` header above it — the box inherits the header's confidence.
- Confusing a low P/E with cheapness (a low multiple on falling earnings is a value trap — see the PFE run in the Cookbook) or a high P/E with expensiveness (growth can justify it; the reverse-DCF in `stock-valuation` says whether it does).
- Reading `Confidence: HIGH` as "high probability the stock goes up" — it means the *data* was strong and the signals agreed, not that the outcome is likely.
- Taking a `bear-case` output as a balanced verdict — it is deliberately one-sided by design.
- Treating a DCF fair value as a fact rather than the output of stated assumptions (change the terminal growth by 1% and watch the value move).
- Anchoring on the average cost or the entry price — the market does not know what you paid.
- Reading `Horizon: LONG-TERM` as permission to stop checking — the Thesis Invalidation section says when to look again.

### Phase 5 — The Socratic ladder

Three to five questions, each harder than the last, each answerable from the pasted analysis plus the cards above. Do not answer them; end the ladder with the standing question.

| Rung | Type | Example shape |
|------|------|---------------|
| 1 | Recall | "Which single metric in this analysis most supports the BULLISH call, and what is its value?" |
| 2 | Interpretation | "The analysis says gross margin is 75% *and* expanding. What does an expanding margin tell you that a high margin alone does not?" |
| 3 | Connection | "If revenue growth slowed to 10% next year but margins held, which of the analysis's conclusions would survive and which would not?" |
| 4 | Judgment | "The valuation section says the price assumes 25% growth for five years. Is that plausible for a company this size? What would you need to see to believe it?" |
| 5 | Transfer | "Take the same three metrics and apply them to a competitor you know. Does the comparison change how you read this company?" |
| — | **Standing question** | **"What would change your mind?"** — answer with the analysis's own Thesis Invalidation triggers; if it has none, write three. |

---

## 4. Framework — Quiz Mode (`--quiz <lesson>`)

Five questions on one Learning lesson, in this fixed mix:

| # | Type | Design rule |
|---|------|-------------|
| 1 | Recall | A definition or a "which statement is true" — answerable straight from the lesson |
| 2 | Recall | A second core term, ideally the one beginners confuse with the first |
| 3 | Calculation | Give a tiny, fully specified data set (three to five numbers) and ask for one computed value — e.g. "Revenue $200M, COGS $120M, opex $50M: what is the operating margin?" Show the worked solution in the answers |
| 4 | Judgment | Two companies described in two lines each; ask which the lesson's framework prefers and *why* |
| 5 | Judgment / transfer | A situation where the naive reading and the correct reading differ (the value-trap pattern, the buyback that hides dilution, the beta that understates risk) |

Format:

```
## Quiz — <Lesson name>  (5 questions · --level <level>)

1. …
2. …
3. … (data: …)
4. …
5. …

## Answers
1. <answer> — <one-line why>
2. …
3. <worked calculation> = <result>
4. …
5. …

**Re-read:** <Lesson name> → <section or concept>, and the Glossary entry for <term>.
```

Never pull questions from outside the named lesson; the point is to confirm the lesson landed, not to test breadth. In `--lang zh-TW` write questions and answers in Traditional Chinese with English metric names in brackets.

---

## 5. Output Format

**Explain mode**
1. `Data & Sources` header (the pasted analysis's own, or the LOW-confidence substitute)
2. **One-line orientation** — which skill produced this, what question it answers, and its signal as stated
3. **Contract check** (Phase 1) — only the pieces that are missing get a paragraph; present pieces get one line each
4. **Explanation cards** (Phase 2), ordered by influence on the signal — three to six full cards, the remaining metrics in a compact table (metric · value · one-line meaning · lesson)
5. **How the pieces connect** (Phase 3)
6. **Common misreadings** (Phase 4)
7. **Socratic ladder** (Phase 5), ending with **What would change your mind?**
8. **Next step** — one line: which lesson to read next, and which skill to run to test the reader's new question
9. Thesis Invalidation (the reader's version — below) and the Investment Signal block, **mirroring the pasted analysis's signal unchanged**, with the Learning Coach note

**Quiz mode** — the quiz block from §4, then the Thesis Invalidation and signal sections below (signal fields may be `n/a` — a quiz has no analysis to mirror; say so in the note).

---

## Example

```
User: [pastes a stock-eval output for a semiconductor company: Piotroski 8/9, ROIC 34%,
      gross margin 75% expanding, forward P/E 38, moat WIDE, signal BULLISH 7.8/10,
      Confidence HIGH, Data & Sources header present, Thesis Invalidation present]
      Explain this to me — I'm new to this.

The assistant reproduces the Data & Sources header, notes all three contract pieces are
present, then writes five cards ordered by influence: ROIC (plain words: "for every $100 the
company invests in itself, it earns $34 a year"; good/bad: >15% strong generally, >25% elite
for semis; Learn it: Quality lesson), gross margin and its trend, the Piotroski F-Score
(what 8 of 9 means and which test it failed), forward P/E of 38 (generic: high; sector: the
upper half for growth semis; "the price already assumes the growth continues"), and the WIDE
moat rating (which of the five moat sources the analysis relied on). The connecting paragraph
says quality metrics carried the call and valuation argued against it, and that the 7.8 is
"quality strong enough to pay up for, but not cheap." Misreadings: 7.8 is not a buy order;
HIGH confidence describes the data, not the odds; P/E 38 is not automatically expensive.
The ladder ends: "What would change your mind?" — and quotes the analysis's own three
invalidation triggers (margin below 70%, growth below 40%, a top customer moving in-house).
Next step: read the Valuation lesson, then run stock-valuation to see what growth the
price implies. The signal block repeats BULLISH · 7.8 · HIGH unchanged.

User: --quiz Valuation --level beginner

The assistant writes five questions on the Valuation lesson — two definitions (intrinsic
value vs. price; what a discount rate is), one calculation (FCF $500M, 20 shares of 50M...
"what is FCF per share, and at a 5% FCF yield what price does that imply?" → $10/share,
$200), one two-company judgment (same P/E, different growth — which is cheaper?), and one
trap (a low P/E on earnings that just halved). Answers under the Answers heading with the
calculation worked out. Re-read: Valuation → "price vs. value", Glossary → FCF yield.
```

---

## Notes

- **Explain, don't re-analyze.** If the reader wants to know whether the analysis is *right*, send them to `result-validator`; if they want the opposite view, to `bear-case`. The coach's value is that it never changes the answer — it changes what the reader understands about it.
- **Match the level honestly.** A beginner who receives an intermediate explanation learns nothing; an intermediate reader who receives definitions of revenue stops reading. When unsure, ask one question about what they already know before writing.
- **Sector ranges are the hardest part and the most valuable.** Always state which sector's norms you are using and why; when the pasted analysis names peers, use them.
- **Quote the analysis, cite the lesson.** Every card should point at where in the pasted text the number came from and where on the site the concept is taught — the reader should be able to check both.
- **Traditional Chinese output** follows the Learning track's own zh-TW pages (`learning-zh-tw.html`, `glossary-zh-tw.html`); link those instead of the English pages when `--lang zh-TW` is set.
- Long inputs: a `full-report` may contain fifteen modules. Explain the composite and the three modules with the largest weight fully; summarize the rest in the compact table and offer to expand any one on request.

## Thesis Invalidation

This skill explains a reading rather than making a call, so what can be invalidated is **the learner's understanding**. After the explanation, state when it stops being valid:

**The explanation no longer applies if:**
- The analysis is re-run and any of the three signal-driving metrics changes band (the cards were written for these values — re-run the coach on the new output rather than re-reading the old one)
- The `Data & Sources` header dates the figures more than 90 days back, or a newer filing has landed since (the meaning of a metric does not age; its value does)
- The pasted analysis is later shown by `result-validator` to have a data or arithmetic error — an explanation of a wrong number is still wrong, however clear
- The reader has moved from beginner to intermediate — the beginner cards now under-explain interpretation and over-explain definitions; re-run at the higher level

**The learner's own reading is invalidated if they cannot:**
- Name the two or three metrics that drove the signal, without looking
- State the good / bad range for the key metric *in this sector*
- Answer "what would change your mind?" with a specific, observable trigger

**Re-run this coach when:**
- [ ] The underlying analysis is re-run (next earnings, price move ±15%, material news)
- [ ] The reader finishes the lesson the cards pointed to — a second pass should feel different
- [ ] The reader runs a *different* skill on the same company (the connections paragraph changes)
- [ ] 60 days have elapsed and the reader wants to check what stuck (use `--quiz`)

## Standard Signal Output

This skill **does not produce a signal of its own**. The block below mirrors the pasted analysis's Investment Signal exactly — same Signal, Confidence, Horizon, Score, Action, and Conviction — so the reader sees the conclusion they were just taught to read, unchanged. If the pasted material has no signal block (or the run is a `--quiz`), fill every field with `n/a` and say so in the note.

All analysis concludes with this standardized block:

```
╔══════════════════════════════════════════════╗
║              INVESTMENT SIGNAL               ║
╠══════════════════════════════════════════════╣
║ Signal:      BULLISH / NEUTRAL / BEARISH     ║
║ Confidence:  HIGH / MEDIUM / LOW             ║
║ Horizon:     SHORT / MEDIUM / LONG-TERM      ║
║ Score:       X.X / 10                        ║
╠══════════════════════════════════════════════╣
║ Action:      BUY / HOLD / SELL               ║
║ Conviction:  STRONG / MODERATE / WEAK        ║
╚══════════════════════════════════════════════╝
```

Score Guide: 8.0–10.0 Strongly Bullish | 6.0–7.9 Moderately Bullish | 4.0–5.9 Neutral | 2.0–3.9 Moderately Bearish | 0.0–1.9 Strongly Bearish
Confidence: HIGH (strong data, clear signals) | MEDIUM (mixed signals) | LOW (limited data, conflicting signals)
Horizon: SHORT-TERM (1 week–3 months) | MEDIUM-TERM (3 months–1 year) | LONG-TERM (1+ years)

**Learning Coach note:** *(one line)* — "After this explanation you should be able to say, in your own words, why the analysis reached `<Signal>` and which `<metric>` would have to change to reverse it." The box above is the analysed skill's conclusion, reproduced without alteration; the coach's contribution is the understanding, not the verdict.

**Disclaimer:** Educational content only. Not financial advice. This skill explains an analysis; it does not endorse, verify, or update its conclusion.