# Teaching notes

## Preferences (from user)

- Lessons must be **dense / detailed** — do not make sparse “one-screen” lessons; user explicitly dislikes thin content per lesson.
- Curriculum shape: **one big overview first**, then **one deep lesson per published skill**.
- Goal depth: **author-level** — flexible use, exact side effects, not just “how to invoke”.
- Language: user communicates in **Chinese**; keep skill names in English (they are the real tokens). Lessons in Chinese with English identifiers.
- Teaching workspace: **repo root** (default).
- Language style (user feedback on batch 0001–0005): lessons were **"不说人话"** — too jargon-dense, telegraphic noun-stacking, terms used before defined. Rewrite rule: **keep the density** (user still wants 详实), but define every term in plain Chinese at first use, write full sentences, open sections with concrete scenarios, and make table cells complete meanings rather than coded shorthand. Skill names / file paths stay in English as before.

## Curriculum plan

1. `0001` — System map of all 22 published skills — **done**
2. Deep dives in flow order (not alphabetical):
   - `0002` setup-matt-pocock-skills — **done**
   - `0003` grilling (+ grill-me, grill-with-docs) — **done**
   - `0004` domain-modeling — **done**
   - `0005` codebase-design — **done**
   - `0006` handoff · `0007` research · `0008` prototype — **done**
   - `0009` to-spec · `0010` to-tickets · `0011` implement · `0012` tdd · `0013` code-review — **done**
   - `0014` triage · `0015` diagnosing-bugs · `0016` wayfinder — **done**
   - `0017` improve-codebase-architecture · `0018` resolving-merge-conflicts — **done**
   - `0019` ask-matt · `0020` writing-great-skills · `0021` teach — **done**
3. Interleave retrieval across lessons; keep `reference/` cheat sheets updated after each deep dive. — all 22 reference docs now exist.

## Parallel write note

Lessons 0002–0005 written in parallel via 4 subagents (`model: grok-4.5`; user asked "grok4.5 high" — only slug available is `grok-4.5`).
Lessons 0006–0021 written in one AgentSwarm batch of 16 subagents (first attempt: 14 failed on provider quota 403, resumed successfully on "继续").

## Material issues found by subagents (follow-ups, not yet acted on)

- `assets/quiz.js` 的反馈文案硬编码了 0001 专用句（"复述主 flow 与三条写 tracker 的 skill"），所有课的 quiz 都会显示。建议改成 `data-*` 可配。
- `docs/engineering/research.md` 引用了不存在的 skill `to-prd`（应为 `to-spec`）——上游仓库问题。
- `ask-matt/SKILL.md` 的地图未收录 `resolving-merge-conflicts`——按 AGENTS.md 规则这是路由缺口（0018、0019 课内已如实说明）。
- `skills/in-progress/claude-handoff/` 是 handoff 的未发布近亲；若将来发布，0006 需补对照节。
- 课程 `CONTEXT.md` 举例 Triage role 用了 `ready-for-afk`，而 setup SKILL.md 默认五角色是 `needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix`——课程统一以 setup 原文为准。
- 课程 `CONTEXT.md` 忌用 ticket，但 `to-tickets` 原文自称 tickets；课程沿用 0001 先例译为「票」，并在 0010 有 callout 约定。

## ZPD notes

- Prior session: user already knows plugin.json = published set; rejected unsolicited study markdown; wants teach-skill structured course.
- Do not re-teach “where is the ship list” beyond a short reminder.