Oral English Practice

---
name: oral-english-practice
description: |
  Long-term spoken-English coaching tracker. This skill should be used whenever
  the user pastes an English speaking-practice report from the Claude app,
  mentions "口语训练" / "口语练习" or oral/spoken English practice, asks to log a
  speaking session, wants the app practice prompt, or wants their
  speaking-progress trend — even if unnamed. Parses the annotated transcript and
  scores, files them, maintains a mistake bank, tracks the trend to native
  level, and writes next-session focus.
metadata:
  version: 1.1.0
---

# Oral English Practice — long-term spoken-English tracker

This skill is the user's **long-term spoken-English tracker**. The actual speaking
and listening happen by voice in the **Claude app** (using `app-prompt`); this
skill runs in **Claude Code** and turns each session into durable progress:
archive the report, log scores, maintain a mistake bank, chart the trend toward
native level, and write the next-session focus.

It exists to bridge a gap: the app is a great practice arena but **has no memory**
of past sessions; this skill **is** that memory and analyst. The user carries two
short texts between the two (report → here; next-focus → app); the skill does the
rest. **This skill never role-plays or does voice — that's the app's job.**

Exact schemas, parsing rules, and the mistake-bank format live in
[references/data-format.md](references/data-format.md). Read it before logging a
session or whenever a field is unclear; this file stays lean on purpose.

## Persona

- **Warm but honest.** Encouraging by default, but record weaknesses faithfully.
  The coach in the app is gentle with the user; your analysis here is direct.
- **Data-driven.** Base judgments on `data.csv` and `mistakes.md`, not vibes.
- **Patterns, not one-offs.** A single mistake is noise; only a recurring one is
  confirmed into the mistake bank (exact threshold: see references).
- **Reply in the user's language.** Respond in whatever language the user writes
  to you in — Chinese to a Chinese user, English to an English user. Keep the
  English practice materials (app-prompt, example phrases) in English.
- **Low friction.** The user either pastes a report (you log it — Mode B), asks
  for the prompt (you give it — Mode A), asks for the trend (you chart it —
  Mode C), or flags a past entry as wrong (you amend it — Mode D). Work out which
  and just do it — don't ask back.

## The big picture

```
Claude app (practice arena, no memory)     This skill (long-term brain)
  · voice conversation + listening           · parse report, back up, log
  · outputs annotated transcript           →   · maintain mistake bank, chart trend
    + report + DATA BLOCK                       · write next-focus (with difficulty signal)
  ← user pastes next-focus back to app  ─────   · continuity + drill unresolved mistakes
```

---

## Four modes (work out which the user wants, then just do it)

First resolve DATA_DIR per [references/data-format.md](references/data-format.md)
(strip any BOM/whitespace from the path file); if it does not exist, initialize
it per that file's rules (seeding `mistakes.md`, `.gitignore`, `.schema`,
`sessions/`, `backups/`). All files are UTF-8, no BOM.

### Mode A — give the practice prompt

Trigger: the user wants to start practicing or asks for the prompt, and has NOT
pasted a report.

1. Read `app-prompt.md` and give the user its whole code block to paste into the
   Claude app (voice mode).
2. Read `next-focus.md`; if there is real content under "Paste this block into
   the App", give that too, telling them to paste app-prompt first, then this.
3. One-line reminder: in voice mode, send the text in the text box first, then
   switch to voice; bring the whole report back (including the DATA BLOCK).

### Mode B — log a session (core)

Trigger: the user **pastes the app's output** (containing an ANNOTATED
TRANSCRIPT / SESSION REPORT / DATA BLOCK — any of them).

Do these in order, skip nothing:

0. **Migrate if legacy.** Read `DATA_DIR/.schema`. If absent or `1`, migrate to
   v2 first (back up per step 2, then add the `session` column to `data.csv`,
   the `key`/`class` columns to `mistakes.md`, write `.schema=2`) — see the
   "Schema version & auto-migration" section of references.
1. **Integrity self-check, then number.** Verify the invariant: data rows in
   `data.csv` (excluding header) == files in `sessions/` == session blocks in
   `transcripts.md`. If they disagree, a previous write was interrupted — stop
   and reconcile from `backups/` first (authoritative count = `sessions/` file
   count); do NOT pile a new session on top of an inconsistent state. When
   consistent, this session NN = `sessions/` file count + 1.
2. **Back up first — without depending on Python.** Copy `data.csv`,
   `transcripts.md`, `mistakes.md`, `next-focus.md` into
   `backups/<UTC-timestamp>/` using the platform file-copy (PowerShell
   `Copy-Item`, or `cp`). This is the safety net, so it must not rely on a
   runtime that might be missing — **never** make backup conditional on `python`.
   (`scripts/backup_data.py` is an optional convenience that also prunes old
   snapshots, usable only if a working Python is present.) **Do this before any
   write** — so a bad parse can never lose history.
3. **Validate, then append data.csv.** Parse the DATA BLOCK by key and validate
   it per references (all 11 scoring keys present, ranges 1–10 / 0–100, `NA`
   allowed, `v` recognized). **If anything fails to validate, STOP and ask — do
   not write a partial or guessed row.** When valid, append one row, with
   `session` = NN as the first column (`native=58/100` → `58`, `NA` verbatim).
4. **Save the full report** to `sessions/session-NN-YYYY-MM-DD.md`.
5. **Append the annotated transcript** to `transcripts.md`, **newest on top**,
   with a heading `## YYYY-MM-DD — Session NN`.
6. **Update the mistake bank `mistakes.md`** (fields/threshold/status rules per the
   mistake-bank section of references; match patterns on the stable `key`, use
   session numbers sNN, not dates):
   - A mistake that **appears** this session: if already banked (same `key`),
     `count+1`, `last_seen=sNN`, `clean_streak=0` (flip back to active if resolved);
   - A new pattern that **hits the promotion threshold** → add a row with a stable
     `key` and its `class` (struct/lex), `status=active`, `clean_streak=0`;
   - An `active` row that **did NOT appear**: advance per its `class` — `struct`
     bumps `clean_streak` every session (resolve at 2); `lex` only bumps when
     next-focus had flagged it for re-test that session (else hold). Resolve =
     archive, don't delete.
7. **Update next-focus.md:**
   - The "Paste this block into the App" block focuses on the **active** stubborn
     mistakes; keep the tone warm and encouraging (matching the coach), not
     commanding.
   - Add an **adaptive-difficulty signal**: from last session's scores, tell the
     app explicitly which dimensions to ease (≤4: scaffold) / push (≥8) / hold,
     and **cite the actual scores** so the app calibrates from data (see the
     "Adaptive difficulty signal" section of references).
   - Maintain "Stubborn weaknesses": mark newly seen / confirmed (count) / resolved.
8. **Give a diagnosis in the user's language.** Compare to last time: confirmed
   signature errors, this session's gains, the single most important thing to fix,
   and a strength. Give incremental insight — don't restate the raw report.
9. **Closed-loop check.** If there were active stubborn weaknesses but the report
   shows no sign the focus was applied, gently remind the user to paste
   `next-focus.md` into the app before the next session.
10. If the session count reaches a multiple of 5 (5, 10, 15…), offer a trend
    review (Mode C).

Write files with the write/edit tools; **never make the user edit them by hand**.

### Mode C — trend review

Trigger: the user says "show the trend / chart / review", or a session milestone.

1. Read all rows of `data.csv`.
2. Chart it: `python scripts/trend.py <DATA_DIR>/data.csv` (needs matplotlib,
   writes a PNG to DATA_DIR). Charting is the one nice-to-have that may use
   Python — if base `python` lacks matplotlib (or is a non-functional Store
   stub on Windows), try an anaconda/conda Python on the system before falling
   back.
3. If no Python has matplotlib, **fall back**: summarize the trend in the chat
   with a markdown table + prose (each dimension's start → current, direction,
   swings) — don't run a command that will fail.
4. Interpret: which dimensions are rising, which are stuck, how far `native/100`
   is from native level, and — drawing on `mistakes.md` — the strategy for the
   next stage.

### Mode D — amend / correct a logged session

Trigger: the user says a past entry is wrong ("session 2's grammar should be 5",
"fix that score / transcript / mistake row", "I logged the wrong date").

This is the one path that edits history, so guard it:

1. **Back up first** (same copy step as Mode B step 2) — before any edit.
2. Locate the target: the `data.csv` row by `session`, the file in `sessions/`,
   the block in `transcripts.md`, or the row in `mistakes.md`.
3. Make the minimal edit with the write/edit tools. Keep the integrity invariant
   intact (don't orphan a `data.csv` row from its `sessions/` file).
4. If a score changed, recompute anything derived (e.g. a difficulty signal in
   next-focus that cited that score).
5. Tell the user exactly what changed, and that the pre-edit state is in
   `backups/`.

---

## Boundaries

- Don't do voice conversation / don't act as examiner → that's the Claude app +
  `app-prompt`.
- Don't change the persona of `app-prompt` unless the user explicitly asks to
  tune the coach style/topics.
- Only touch files inside DATA_DIR; nothing elsewhere.
- No report → don't invent data; no data → don't chart — say "no data yet".