[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CBFVG8QJXK0EN7CCNW1XWT":3,"skill-same:01M7CBFVG8QJXK0EN7CCNW1XWT":102},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M7CBFVG8QJXK0EN7CCNW1XWT","write-mastery-chapter",null,"Use when authoring a new theory-then-practice study chapter for any subject as a LaTeX PDF (with figures and predict-the-picture exercises), or when revising a chapter this skill previously produced because a specific section was confusing during study.","salomepoulain\u002Fmakery-stations","salomepoulain","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F136823771?v=4","01M7CB5VTPHHYMZVFGCT9YWMQW","Salomé Poulain","01M7CB5VVC773WAEPQM1HE1RTR",0,"MIT","https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: write-mastery-chapter\ndescription: Use when authoring a new theory-then-practice study chapter for any subject as a LaTeX PDF (with figures and predict-the-picture exercises), or when revising a chapter this skill previously produced because a specific section was confusing during study.\n---\n\n# Write mastery chapter\n\nBuild a study chapter the way a good worked-example-driven mastery textbook does it:\nrepetition before escalation, understanding over memorization, every new idea earning its\nworked example before the reader is asked to reproduce it alone.\n\n## Overview\n\nOne core principle governs everything below: **drill the current core skill flat before\nescalating, and escalate late and rarely.** See\n[reference\u002Fpedagogy-cycle.md](reference\u002Fpedagogy-cycle.md) for the full cycle this implies\n(Theory → Recipe → Worked example → tagged exercises, the P O T D V E C R taxonomy, the\ncheckpoint-exercise branch, the Review\u002Fend-of-paragraph cheat sheet). Read it before authoring\nanything. It is the pedagogical spec this skill exists to enforce, not optional background.\n\n**Default scope: full mastery, not compact exam prep.** Unless the user explicitly asks for a\nshort version, the chapter is allowed to become long. Do not omit prerequisite steps, edge\ncases, counterexamples, boring mechanical drills, or hard variants merely to keep the PDF short.\nThe chapter's structure gives the reader control over what to skip: T\u002FD\u002FV\u002FE are the core path,\nC and R are optional depth, Prior knowledge is for prerequisites. Completeness belongs in the\nchapter; selectivity belongs in the exercise tags and reading path.\n\n**Drill means one move across many surfaces.** In Full Mastery mode, a Drill exercise is not a\nsmall mixed quiz. It is one named family of the same move, repeated across several nearby\nsituations until the reader can recognise the move without thinking. A good Drill family may\nhave four, six, eight or even nine lettered parts when the invariant is stable: same task,\ndifferent numbers, shapes, signs, dimensions, zero\u002Fidentity cases, symbolic versions, or a\nnear-mistake at the end. Do not satisfy the D row by writing three tiny unrelated questions.\nSee `reference\u002Fpedagogy-cycle.md` for the bad\u002Fgood Drill examples; follow those examples when\nauthoring.\n\n**Bridge concepts are Theory, not glue text.** Completeness also means expanding the small\nnotation and algebra bridges that make source questions learnable from the baseline. Matrix\nshapes, entries, transposes, Sigma notation, matrix products, Kronecker deltas, scalar-transpose\nfacts, inverse assumptions, definiteness checks and convention translations should become their\nown Theory blocks when the chapter relies on them. Do not hide them inside one dense block to\nmake the outline shorter.\n\n**Turn hidden steps into teachable moments.** Do not treat Theory blocks as mathematical\nencyclopedia entries. Treat them as learner obstacles being removed. When a source question needs a\nnotation habit, shape habit, convention, tiny algebra trick, or common wrong-move correction, teach\nthat habit before the source question uses it. Reused habits usually deserve their own Theory\nblock; one-off tripwires can be a named teaching beat inside the current Theory block, with a tiny\nexample, shape check, or counterexample.\n\n**No compression by hiding skills.** A topic may be compressed only after an explicit\ncompression audit: list the skills being merged, the first place each is used, the exercises\nthat drill it, and the edge cases still covered. If a merged block would contain two genuinely\nnew moves, split it. A mastery chapter should feel like a careful staircase, not a summary with\npractice attached.\n\nThe exact LaTeX this produces (colors, box structure, numbering, provenance markers,\ncross-reference hyperlinks) is fully specified in\n[reference\u002Flatex-scaffolding.md](reference\u002Flatex-scaffolding.md). Follow it exactly, this is\nnot a style suggestion, it's the house style contract. A chapter that reads well but uses\ndifferent macros or colors has not followed this skill.\n\nTwo standing assumptions apply to everything authored, both spelled out in\n`reference\u002Fpedagogy-cycle.md` under \"Baseline knowledge\": the reader knows only the baseline the\ncourse or user has named, plus what earlier chapters of the same course taught, and nothing\nelse; the reader needs a hand on every single step. Prior knowledge is everything the chapter's\ntheory builds on from that baseline or from an earlier chapter, and gets extra drilling, never\nless.\nDo not put new chapter material into Prior knowledge just because it is convenient to introduce\nearly. If a concept is not already known from the baseline or an earlier chapter, it gets its\nown Theory block in the numbered chapter.\n\n**Design system.** The finished pilot defines the look of the chapter: the margin pills, the headers, the Contents with\nclickable pills, the short Legend, breakable solutions, source tags in the margin. Read\n[reference\u002Fdesign-system.md](reference\u002Fdesign-system.md) and copy `reference\u002Fpreamble-visual.tex` as the preamble. Where\n`reference\u002Flatex-scaffolding.md` disagrees with them, the design system wins.\n\n**Opening contract.** The opening is not just \"use the right macros\"; it must use the house\norder and the house plumbing. The first visible pages are title\u002Fintroduction plus Contents on\npage 1, the same locked Legend page starting on page 2, then Prior knowledge. The Legend is not\nauthored per chapter: copy the project's `reference\u002Flegend-template.tex` verbatim into the\nchapter body after the Contents. This template may contain project-local example labels; preserve\nthem unless the user deliberately creates a new locked template for a different course or\nproject. Then start `\\begin{priorsection}\\priortitle` and immediately add\n`\\addtocontents{toc}{\\protect\\dcrowflat{0}}`. That last line is what puts the Prior-knowledge\npills into the Contents; omitting it is a structural bug, even if the chapter compiles.\n\n**Visual intuition.** Every chapter has figures and a pink `V` exercise type that makes the reader\npredict a picture before seeing it. Read [reference\u002Fvisual-intuition.md](reference\u002Fvisual-intuition.md)\nbefore authoring: it says where figures go, what a V exercise asks, how the questions PDF shows\nempty axes while the answers PDF shows the curves, and how to build and check a figure.\nFor any idea that has a visual, geometric, tabular, computational-graph, timeline, state-machine,\nnumber-line, flow, contour, or before\u002Fafter representation, put that representation inside the\nTheory block before or beside the abstraction. If the subject is abstract, make the visual from\na small concrete instance: a table, diagram, trace, grid, annotated expression, or dependency\ngraph. A V exercise later is not a substitute for visualizing the Theory itself.\n\n**REQUIRED SUB-SKILL:** run `humanize` on every piece of authored prose as the last step of any\ninvocation, in either mode. No em dashes, no AI-tell phrasing. Run it after the content is\ncorrect, never before: it should polish the prose, not change meaning or math.\n\n## What this skill produces\n\nEverything for one chapter goes into its own subfolder of `lessons\u002F` in the project root (`\u003Cproject root>\u002Flessons\u002F`, not\ninside `.vault\u002F`). Create `lessons\u002F` if it does not exist. The subfolder's name is the chapter's own base name, the same\nstring every file in it starts with, so the folder and its files always read as one unit:\n```\nlessons\u002F\n  \u003Ccourse>-chap\u003CN>-\u003Ctopic>-chapter\u002F\n    \u003Ccourse>-chap\u003CN>-\u003Ctopic>-chapter.tex             the only source: preamble, content, Legend, Contents, Summary, Diagnostic check\n    \u003Ccourse>-chap\u003CN>-\u003Ctopic>-chapter-answers.pdf     with every solution\n    \u003Ccourse>-chap\u003CN>-\u003Ctopic>-chapter-questions.pdf   without solutions (blank space where they were, empty axes on V exercises)\n    \u003Ccourse>-chap\u003CN>-\u003Ctopic>-coverage.md             inventory of the input material and one row per source question part\n    build-chapter.sh, mastery-breaks.sty             copied in by the first build, so the folder builds by itself\n    (per PDF: .aux .log .out .toc                    build leftovers, safe to delete)\n  \u003Ccourse>-chap\u003CM>-\u003Cother-topic>-chapter\u002F            the next chapter of the same course, its own subfolder the same way\n    ...\n```\nThe chapters of one course sit side by side as subfolders of `lessons\u002F`, so the \"find the earlier chapters\" search in\nMode A step 1 looks for `lessons\u002F\u003Ccourse>-chap\u003CM>-*-chapter\u002F\u003Ccourse>-chap\u003CM>-*-chapter.tex` (M \u003C N). Course-level files that\nspan more than one chapter (a division plan, a shared study note) go directly in `lessons\u002F`, not inside any single\nchapter's subfolder. Only if the user names a different location, use that one.\nFigures are pgfplots code inside the `.tex`, so there are no image files. The chapter needs a TeX Live with `tcolorbox`, `pgfplots`, `enumitem`, `microtype` and\n`hyperref` (see the Dependencies section of `reference\u002Flatex-scaffolding.md`). Build with\n`bash \u003Cskill>\u002Freference\u002Fbuild-chapter.sh \u003Ccourse>-chap\u003CN>-\u003Ctopic>-chapter` from inside the folder; it copies `mastery-breaks.sty` and itself next to the chapter.\n\n## Which mode\n\n- No chapter exists yet for this subject, or the user wants one written from scratch →\n  **Mode A: author a new chapter**.\n- A chapter this skill already produced exists, and the user is pointing at a specific passage\n  that confused them (a quote, a screenshot, a description of \"this part\") →\n  **Mode B: confusion-driven update**.\n\nIf genuinely unclear which applies (e.g. the user wants both a new topic added to an existing\nchapter *and* a specific passage fixed), ask instead of guessing. These two modes have\ndifferent gates and a different blast radius.\n\n## Grounding dispatch\n\nBefore authoring or rewriting any technical content (a formula, a definition, a claim), check\nit's actually correct. If the target project has a vault (a `.vault\u002F` folder, or similar\nknowledge base), dispatch a `general-purpose` agent: find and read the vault's own schema file\nfirst, check for existing coverage there before falling back to a web search, and report back\nfindings\u002Fsources\u002Fgaps. Restate this guardrail verbatim in every such dispatch:\n\n> This pass is read-only. The agent must never write, move, or delete anything in the vault or\n> in any project file. If it finds something worth permanently recording, it reports that as a\n> gap for a separate, deliberate follow-up. It does not act on it itself.\n\nFor a quick fact-check mid-authoring, use the same dispatch with a narrower question instead of\na broad topic.\n\n## Mode A: author a new chapter\n\n**Language.** Write the chapter's own prose (titles, Legend, Theory, worked examples, exercises,\nsolutions, Reviews, Summary, Diagnostic check, figure and axis labels, source tags) in the\nlanguage the course's own input material uses (its lectures, homework, exams), not the language\nof the user's chat request. Names of curricula, exams, institutions and source files stay in\ntheir own language as proper nouns. If the input material is not clearly all in one language,\nask.\n\n1. **Ground the subject and take inventory.** Grounding dispatch (above) on the subject matter itself: what are\n   the real first principles, standard framings, common gotchas. Ask the user which folders hold the input material\n   (homework, practice sets, past exams, lecture notes, summaries) unless they already said, and also look in the project's vault for the\n   subject. **List every file** in those folders and **open every one completely** (a PDF page by page, nothing skimmed). Record file, type, page count and number of\n   question parts. Check [examples\u002F](examples\u002FREADME.md) too. The input material is the highest-signal source for which edge cases actually matter,\n   more useful than a generic treatment of the topic. Anything not opened is reported as a gap, never silently skipped.\n\n   **Find the course dependency baseline.** Before deciding Prior knowledge, search `lessons\u002F`\n   for course-level planning or baseline files such as `\u003Ccourse>-dependency-baseline.md`,\n   `\u003Ccourse>-chapter-division.md`, `\u003Ccourse>-*-chapter-estimate.md`, or similarly named files.\n   Read the relevant ones and treat them as the project-local source for the named baseline.\n   The skill remains generic; the course repository states what the baseline is.\n\n   **Find the earlier chapters.** Prior knowledge builds on the previous chapters of the same course, so before planning, look for them. Work out this chapter's\n   number N (from the request or the file name), then search the project for chapters M \u003C N of the same course: `\u003Cproject root>\u002Flessons\u002F`, the vault, and\n   the file name pattern `\u003Ccourse>-chap\u003CM>-*-chapter\u002F\u003Ccourse>-chap\u003CM>-*-chapter.tex` (see \"What this skill produces\" above). Read every one you find (its Theory titles, its Review terms and formulas, its Summary): that is what the\n   reader has already been taught and may be used without teaching it again. Record them in the inventory (chapter, file, Theory letters and titles). If N > 1 and no earlier\n   chapter is found, ask the user whether earlier chapters exist elsewhere before assuming none do. Chapter 1 has no earlier course chapter, so its Prior knowledge comes only from the named baseline.\n\n   **Study exemplars for method, not content.** If the user points to a previous chapter or PDF\n   whose pedagogy or visuals they like, inspect it and extract reusable method patterns: how\n   Theory moves from concrete picture to formula, how exercises escalate, how edge cases are\n   surfaced, and how the Diagnostic check mirrors the chapter. Do not copy subject-specific\n   claims unless they are part of the current subject and independently grounded.\n\n2. **Draft a plan and present it in chat**: a paragraph-by-paragraph (`§1`, `§2`, ...) outline,\n   each paragraph's Theory-block breakdown, and a rough exercise-tag count per block (how many\n   plain items, whether an R\u002FA\u002FD shows up, whether a Prior-knowledge block is needed first).\n   The default plan is a **Full Mastery** plan. It must include all in-scope source material and\n   all prerequisite bridges needed to make that material learnable from the baseline. A compact\n   plan is allowed only when the user explicitly asks for a compact chapter.\n   Also give the **dependency list**: for every Prior block, its source (the named course baseline, a baseline reference file when available, or the earlier chapter and its Theory letter,\n   which you found and read in step 1) and the Theory blocks\n   or exercises that use it before the chapter teaches it. A skill that nothing depends on is not Prior knowledge, and a skill the\n   chapter teaches itself is Theory (see \"What Prior knowledge is\" in `reference\u002Fpedagogy-cycle.md`).\n   Give an **edge-case and variation map** per Theory block: ordinary case, smallest nontrivial\n   case, shape\u002Ftype\u002Fdomain boundary, zero\u002Fidentity\u002Fempty or constant case where relevant,\n   symmetric\u002Fdegenerate\u002Fsingular or non-invertible case where relevant, sign\u002Fcorner\u002Flimit case\n   where relevant, and one common wrong move the chapter will explicitly inoculate against.\n   Irrelevant categories may be marked \"not applicable\"; unmentioned categories are treated as\n   unplanned, not implicitly absent.\n   Also say, per paragraph, which Theory blocks get a figure and which get a V exercise, and how many V exercises the paragraph has\n   (2 to 4, fewer only with a stated reason; see visual-intuition.md). For every block give the 3Blue1Brown source of the picture\n   (the search step \"Find the 3Blue1Brown material first\" in visual-intuition.md, done during step 1) and write the \"Visual sources\" table into `\u003Cname>-coverage.md`.\n   Also state the **Theory visual hook** for every Theory block: the concrete picture, table,\n   graph, diagram, trace, or tiny example that appears inside the Theory before the general\n   formula. If a block truly has no meaningful visual hook, say why and include a concrete\n   nonvisual representation instead.\n   Also give the Theory-block count per paragraph, and cut paragraphs by topic (see \"Where to cut\n   a chapter into paragraphs\" in `reference\u002Fpedagogy-cycle.md`; the sizes there are a guideline).\n   If the subject is clearly built on the target project's existing material, say what it\n   connects to and why.\n   Also list every question part in the input material and mark it in scope or out of scope, with a reason for each out of scope (the chapter or topic it belongs to).\n   Every in-scope part must end up in the chapter, in its own wording, with a solution that\n   matches the source solution's method and result (see \"Source questions and solutions are\n   mandatory\" in `reference\u002Fpedagogy-cycle.md`). Put the inventory and this coverage list in the plan, and write them to `\u003Cname>-coverage.md` next to the chapter.\n   Include a **no-omission declaration**: what would normally be tempting to skip, where it is\n   taught instead, and which optional tag lets a rushed reader skip it without removing it from\n   the chapter.\n\n3. **Stop and wait for the user's explicit go-ahead before writing anything.** Do not start\n   Mode A step 4 until they confirm the plan. This is a hard gate, not a formality. The plan\n   is cheap to redirect; 40 pages of LaTeX is not.\n\n**Supervised authoring: steps 4 to 8 are not one unsupervised dispatch.** Once the plan is approved, whoever is running\nthis skill (the main conversation, or an agent it dispatches to write) stays the orchestrator for the whole build and\ncheckpoints after every paragraph, even when the user has waived the step-3 plan gate for that run or asked for it to run\nstraight through without asking again. A single subagent authoring 40 to 200 pages unattended, however good its\ninstructions, drifts: it satisfies whatever is checked by a script and quietly lets whatever isn't checked slide,\nespecially the plain-English rules that have no automated check (a chapter authored this way once shipped with a third of\nits Drill exercises and a Legend that silently reverted to a stale, wrong template, both invisible until someone actually\nopened the PDF). The fix is not to trust the instructions harder, it is to look at the output before it compounds:\n\n- Dispatch (or resume) the authoring agent one stage at a time: the opening (title, Contents, Legend, Prior knowledge),\n  then one paragraph at a time. Tell it to build and report after each stage, per step 5 below, exactly as it already does\n  for its own progress log.\n- After **every** stage, the orchestrator itself (not a claim from the subagent's report) runs\n  `reference\u002Fcheck-chapter.py` on the chapter so far and reads all of its tables: EXERCISE RUN per Theory block (every\n  block just added needs D >= 3, per \"Exercise taxonomy\" in `reference\u002Fpedagogy-cycle.md`; a block under that is not\n  finished, send the same stage back before moving on), VISUALS per paragraph, THEORY BLOCK DENSITY, and LEGEND STRUCTURE.\n  A flag anywhere is not a note for later, it is the same stage's work, unfinished; resolve it before dispatching the next\n  stage, the same way a real editor reviews a chapter before the next one is drafted, not after the book is bound.\n- After the **opening** stage specifically, render the Contents and Legend pages to PNG and read them, don't just trust\n  `LEGEND STRUCTURE`'s text-level check. They are written once and never touched again, so a mistake here silently\n  affects every later stage.\n- After each **paragraph** stage, render and read at least one Theory box, the exercise run of one block, and one V\n  exercise's question and solution pages, the way step 7 below describes for the finished chapter, just done per stage\n  instead of only at the very end.\n- After each **paragraph** stage, run a completeness review against the plan's edge-case and\n  variation map. Every edge case promised in the plan must be either taught, drilled, placed in\n  C\u002FR, or explicitly deferred to a named later chapter. Do not silently drop edge cases to keep\n  the chapter short.\n- Only once a stage passes all of this does the orchestrator dispatch the next one. This costs more of the orchestrator's\n  own attention than firing one long instruction and waiting, that cost is the point: it is what catches a thin block or a\n  reverted template while it is a five-minute fix instead of a full rewrite.\n\n4. **Author one file**, `\u003Cname>-chapter.tex` (one source, two PDFs: with and without\n   solutions, see \"File structure\"), exactly per\n   [reference\u002Flatex-scaffolding.md](reference\u002Flatex-scaffolding.md)'s file structure and macro\n   set, exactly per [reference\u002Fpedagogy-cycle.md](reference\u002Fpedagogy-cycle.md)'s cycle and\n   presentation convention. Name the file `\u003Ccourse>-chap\u003CN>-\u003Ctopic>-chapter.tex` (for example\n   `ml1-chap1-mvcalc-chapter.tex`), with the chapter number right after the course prefix, so the\n   files sort in chapter order. If the target project already has a different chapter naming\n   convention (check its vault\u002Fdocs for other chapters this skill or a\n   predecessor produced). Every chapter opens with the title, Contents, locked Legend and Prior\n   knowledge in the house order;\n   see latex-scaffolding.md's \"Required opening\" section for the exact structure.\n\n   Author to full mastery depth by default. For each Theory block, include a concrete setup,\n   the visual or structural intuition, the formal statement, a worked example with every move\n   shown, then the T\u002FD\u002FV\u002FE\u002FC\u002FR run. Challenge exercises are not decorative: they protect edge\n   cases, unusual framings and common traps. A chapter with no Challenge exercises needs an\n   explicit user-approved reason.\n\n5. **Compile and verify.** Build both PDFs with `reference\u002Fbuild-chapter.sh` (it also lets LaTeX find `reference\u002Fmastery-breaks.sty`; three `pdflatex` passes each: hyperref\n   needs a second pass to resolve labels, and the table of contents needs a third to reflect page\n   numbers that shifted once it was inserted). Confirm zero errors (`grep -c '^!'` the log). Confirm no\n   undefined references. Render figure pages to PNG and look at them, in both PDFs. If `tcolorbox`\u002F`hyperref` aren't installed in the target environment,\n   see the Dependencies section of `reference\u002Flatex-scaffolding.md` for the\n   `tlmgr --usermode install` fix. This is a known, solvable hurdle, not a reason to fall back\n   to a different box design.\n\n   **Check the Contents fits on page 1** (design-system.md's \"Page 1 holds the title, the introduction and the Contents in\n   full\"), every time, not only for a long chapter: `pdftotext -layout -f 1 -l 1 \u003Cname>-chapter-answers.pdf -` and read off\n   the page number printed after \"Legend\" in the Contents listing. It must say 2. Any other number means the Contents\n   spilled onto page 2, shorten the introduction per design-system.md's order and rebuild before moving on.\n\n6. **Check the breaks** (rules in `reference\u002Fdesign-system.md`, \"Line and page breaks\"). In the questions PDF, scan every page break:\n   an exercise intro alone at a page bottom, a single part alone at a page top or bottom, a Theory paragraph cut in the middle, a solution\n   separated from its part. Look at `Overfull \\hbox` in both logs: each one is a long inline formula, turn it into a display. Grep the log for `has no \\newterm`: every `\\tm` key must be a term introduced in the Theory.\n\n7. **Visually spot-check the actual PDF**, not just the compile log: box seams (Theory and\n   Worked example should read as one continuous region with a subtle tone shift, not a visible\n   gap), any page break that lands inside a box (should be clean, no duplicated title), that\n   cross-reference hyperlinks actually resolve to the right place, and that the Contents (on the title page) lists every `\\frontsection` (Legend, Prior knowledge,\n   Summary, Diagnostic check). Also count plain exercises per Theory\n   block; fewer than 3 means go back and add more before calling a block finished, per\n   `reference\u002Fpedagogy-cycle.md`.\n\n   Then run the checks: `python3 \u003Cskill>\u002Freference\u002Fcheck-chapter.py \u003Cname>-chapter.tex \u003Cname>-coverage.md`. It lists the solutions that are too short for their\n   type (see \"Solutions: how extensive\" in `reference\u002Fpedagogy-cycle.md`: extend them or justify them) and checks the coverage file against the chapter: every\n   in-scope source question part appears, in its own wording, and each solution was compared against the source solution.\n   Also read the Summary and Diagnostic rows in the rendered Contents. The Summary must show\n   the Theory-letter snake, and the Diagnostic check must show its number pills. The Diagnostic\n   must mirror the chapter: at least one group per numbered paragraph, with fresh questions\n   covering the paragraph's core skills and at least one mixed\u002Fcapstone group when the chapter\n   culminates in source-style or exam-style problems.\n\n8. **Humanize pass** (see Overview) on the authored prose.\n\n9. Report back to the user for judgment. Don't declare success yourself: a clean compile is\n   necessary, not sufficient.\n\n## Token-efficient authoring exception\n\nWhen the user asks for a token-efficient run, checkpoint the opening and then batches of\ntwo or three numbered paragraphs. Use a one-paragraph checkpoint only for unusually risky\nmaterial or when the user requests it. After each batch, report only changed files, counts,\nhard failures, and unresolved questions, in at most ten lines.\n\nRun the checker after each batch, but show only its summary: exercise and visual counts,\nTheory density, opening\u002FLegend status, source-label count, and coverage failures. Treat\nmissing labels, missing Theory hooks, too few Drill families, malformed structure, coverage\nfailures, and LaTeX errors as blockers. Treat short-solution listings as review signals:\nalways fix bare answers and incomplete E\u002FC\u002FDiagnostic arguments, but do not mechanically\npad a compact atomic Drill or shape answer that already states its reason and result.\n\nRender Contents and Legend once after the opening, one Theory page and one V question\u002Fsolution\npair per later batch, and a selected-page final spot-check. Do not render every page unless\nan automated check reports a layout problem. If the user explicitly allows a multi-page\nContents, verify its order, readability, and links instead of forcing it onto one page.\n\n## Mode B: confusion-driven update\n\nA concrete procedure, not vague guidance. This is exactly what manual, successful fixes to a\nchapter's source look like in practice:\n\n1. **Locate the exact source location.** From the user's pointer (a quote, a screenshot, \"the\n   part about X\"), grep the chapter body for the nearest heading\u002Flabel or distinctive phrase,\n   then read that section directly to confirm you've found the right spot before touching\n   anything.\n\n2. **Classify the confusion into a concrete repair.** Don't default to \"explain it better in\n   chat\"; the fix belongs in the source, so the next reader doesn't hit the same wall:\n   - A fact or step was *used* but never *established* → promote it into a proper new Theory\n     subsection, built up from a concrete case, not asserted mid-derivation. (For example, a\n     derivation leans on \"a scalar equals its own transpose\" without ever having shown it.\n     The fix is a new Theory block deriving that fact from a 1×1-matrix argument, not a\n     one-line parenthetical.)\n   - A derivation jumped steps → expand it into more `align*` lines, one atomic move per line,\n     per the presentation convention.\n   - A prerequisite is missing → add a `refreshbox` (pale yellow, amber P badge) with a concise\n     recap plus a `\\Pbadge` exercise, right before its first use in the paragraph. If the gap is\n     big enough that a recap would not do, extend the opening Prior knowledge section instead.\n     Anything that is genuinely new material gets a full Theory block, not a refresher.\n   - A Worked example is hard to follow because it's doing too much at once → split it: end\n     the first stage, write `\\workedheading` again with \"Worked example (continued)\" for the\n     next stage, still inside the same `theorybox`, rather than cramming a multi-stage\n     derivation into one dense block. (`breakable` handles page-length overflow automatically,\n     so this split is about *clarity*, not page fitting.)\n   - Something was introduced with no motivation (\"why are we even doing this\") → add the\n     motivating sentence or two before the Theory box, or fold it into the box's own opening,\n     not as a floating unstyled paragraph between boxes. Floating prose outside any box is\n     itself a smell; every explanation lives inside a box.\n\n3. **Gate structural changes, not small ones.** Inserting a new Theory block or Prior-knowledge\n   subsection reflows the `\\exnum` stream after it, so confirm the plan with the user first, the\n   same way Mode A gates before writing. A small in-place expansion (more `align*` lines, an\n   added sentence) doesn't need a gate, just do it.\n\n4. **Edit the `.tex` source directly.** Never respond with only a chat explanation when the\n   confusion is about chapter content. The explanation belongs in the file future readers\n   (including a future you) will actually read. Note that `\\secref`\u002F`\\thyref` links elsewhere\n   in the chapter stay correct automatically after an insertion, since they're symbolic labels,\n   not hardcoded numbers.\n\n5. **Rebuild both PDFs** with `build-chapter.sh`, confirm zero errors.\n\n6. **Humanize pass** on the new\u002Fedited prose.\n\n7. Confirm the fix addresses what was actually asked, briefly, without re-explaining the whole\n   section back to the user. They asked about one spot, not a summary of the chapter.\n","# Write mastery chapter\n\nBuild a study chapter the way a good worked-example-driven mastery textbook does it:\nrepetition before escalation, understanding over memorization, every new idea earning its\nworked example before the reader is asked to reproduce it alone.\n\n## Overview\n\nOne core principle governs everything below: **drill the current core skill flat before\nescalating, and escalate late and rarely.** See\n[reference\u002Fpedagogy-cycle.md](reference\u002Fpedagogy-cycle.md) for the full cycle this implies\n(Theory → Recipe → Worked example → tagged exercises, the P O T D V E C R taxonomy, the\ncheckpoint-exercise branch, the Review\u002Fend-of-paragraph cheat sheet). Read it before authoring\nanything. It is the pedagogical spec this skill exists to enforce, not optional background.\n\n**Default scope: full mastery, not compact exam prep.** Unless the user explicitly asks for a\nshort version, the chapter is allowed to become long. Do not omit prerequisite steps, edge\ncases, counterexamples, boring mechanical drills, or hard variants merely to keep the PDF short.\nThe chapter's structure gives the reader control over what to skip: T\u002FD\u002FV\u002FE are the core path,\nC and R are optional depth, Prior knowledge is for prerequisites. Completeness belongs in the\nchapter; selectivity belongs in the exercise tags and reading path.\n\n**Drill means one move across many surfaces.** In Full Mastery mode, a Drill exercise is not a\nsmall mixed quiz. It is one named family of the same move, repeated across several nearby\nsituations until the reader can recognise the move without thinking. A good Drill family may\nhave four, six, eight or even nine lettered parts when the invariant is stable: same task,\ndifferent numbers, shapes, signs, dimensions, zero\u002Fidentity cases, symbolic versions, or a\nnear-mistake at the end. Do not satisfy the D row by writing three tiny unrelated questions.\nSee `reference\u002Fpedagogy-cycle.md` for the bad\u002Fgood Drill examples; follow those examples when\nauthoring.\n\n**Bridge concepts are Theory, not glue text.** Completeness also means expanding the small\nnotation and algebra bridges that make source questions learnable from the baseline. Matrix\nshapes, entries, transposes, Sigma notation, matrix products, Kronecker deltas, scalar-transpose\nfacts, inverse assumptions, definiteness checks and convention translations should become their\nown Theory blocks when the chapter relies on them. Do not hide them inside one dense block to\nmake the outline shorter.\n\n**Turn hidden steps into teachable moments.** Do not treat Theory blocks as mathematical\nencyclopedia entries. Treat them as learner obstacles being removed. When a source question needs a\nnotation habit, shape habit, convention, tiny algebra trick, or common wrong-move correction, teach\nthat habit before the source question uses it. Reused habits usually deserve their own Theory\nblock; one-off tripwires can be a named teaching beat inside the current Theory block, with a tiny\nexample, shape check, or counterexample.\n\n**No compression by hiding skills.** A topic may be compressed only after an explicit\ncompression audit: list the skills being merged, the first place each is used, the exercises\nthat drill it, and the edge cases still covered. If a merged block would contain two genuinely\nnew moves, split it. A mastery chapter should feel like a careful staircase, not a summary with\npractice attached.\n\nThe exact LaTeX this produces (colors, box structure, numbering, provenance markers,\ncross-reference hyperlinks) is fully specified in\n[reference\u002Flatex-scaffolding.md](reference\u002Flatex-scaffolding.md). Follow it exactly, this is\nnot a style suggestion, it's the house style contract. A chapter that reads well but uses\ndifferent macros or colors has not followed this skill.\n\nTwo standing assumptions apply to everything authored, both spelled out in\n`reference\u002Fpedagogy-cycle.md` under \"Baseline knowledge\": the reader knows only the baseline the\ncourse or user has named, plus what earlier chapters of the same course taught, and nothing\nelse; the reader needs a hand on every single step. Prior knowledge is everything the chapter's\ntheory builds on from that baseline or from an earlier chapter, and gets extra drilling, never\nless.\nDo not put new chapter material into Prior knowledge just because it is convenient to introduce\nearly. If a concept is not already known from the baseline or an earlier chapter, it gets its\nown Theory block in the numbered chapter.\n\n**Design system.** The finished pilot defines the look of the chapter: the margin pills, the headers, the Contents with\nclickable pills, the short Legend, breakable solutions, source tags in the margin. Read\n[reference\u002Fdesign-system.md](reference\u002Fdesign-system.md) and copy `reference\u002Fpreamble-visual.tex` as the preamble. Where\n`reference\u002Flatex-scaffolding.md` disagrees with them, the design system wins.\n\n**Opening contract.** The opening is not just \"use the right macros\"; it must use the house\norder and the house plumbing. The first visible pages are title\u002Fintroduction plus Contents on\npage 1, the same locked Legend page starting on page 2, then Prior knowledge. The Legend is not\nauthored per chapter: copy the project's `reference\u002Flegend-template.tex` verbatim into the\nchapter body after the Contents. This template may contain project-local example labels; preserve\nthem unless the user deliberately creates a new locked template for a different course or\nproject. Then start `\\begin{priorsection}\\priortitle` and immediately add\n`\\addtocontents{toc}{\\protect\\dcrowflat{0}}`. That last line is what puts the Prior-knowledge\npills into the Contents; omitting it is a structural bug, even if the chapter compiles.\n\n**Visual intuition.** Every chapter has figures and a pink `V` exercise type that makes the reader\npredict a picture before seeing it. Read [reference\u002Fvisual-intuition.md](reference\u002Fvisual-intuition.md)\nbefore authoring: it says where figures go, what a V exercise asks, how the questions PDF shows\nempty axes while the answers PDF shows the curves, and how to build and check a figure.\nFor any idea that has a visual, geometric, tabular, computational-graph, timeline, state-machine,\nnumber-line, flow, contour, or before\u002Fafter representation, put that representation inside the\nTheory block before or beside the abstraction. If the subject is abstract, make the visual from\na small concrete instance: a table, diagram, trace, grid, annotated expression, or dependency\ngraph. A V exercise later is not a substitute for visualizing the Theory itself.\n\n**REQUIRED SUB-SKILL:** run `humanize` on every piece of authored prose as the last step of any\ninvocation, in either mode. No em dashes, no AI-tell phrasing. Run it after the content is\ncorrect, never before: it should polish the prose, not change meaning or math.\n\n## What this skill produces\n\nEverything for one chapter goes into its own subfolder of `lessons\u002F` in the project root (`\u003Cproject root>\u002Flessons\u002F`, not\ninside `.vault\u002F`). Create `lessons\u002F` if it does not exist. The subfolder's name is the chapter's own base name, the same\nstring every file in it starts with, so the folder and its files always read as one unit:\n```\nlessons\u002F\n  \u003Ccourse>-chap\u003CN>-\u003Ctopic>-chapter\u002F\n    \u003Ccourse>-chap\u003CN>-\u003Ctopic>-chapter.tex             the only source: preamble, content, Legend, Contents, Summary, Diagnostic check\n    \u003Ccourse>-chap\u003CN>-\u003Ctopic>-chapter-answers.pdf     with every solution\n    \u003Ccourse>-chap\u003CN>-\u003Ctopic>-chapter-questions.pdf   without solutions (blank space where they were, empty axes on V exercises)\n    \u003Ccourse>-chap\u003CN>-\u003Ctopic>-coverage.md             inventory of the input material and one row per source question part\n    build-chapter.sh, mastery-breaks.sty             copied in by the first build, so the folder builds by itself\n    (per PDF: .aux .log .out .toc                    build leftovers, safe to delete)\n  \u003Ccourse>-chap\u003CM>-\u003Cother-topic>-chapter\u002F            the next chapter of the same course, its own subfolder the same way\n    ...\n```\nThe chapters of one course sit side by side as subfolders of `lessons\u002F`, so the \"find the earlier chapters\" search in\nMode A step 1 looks for `lessons\u002F\u003Ccourse>-chap\u003CM>-*-chapter\u002F\u003Ccourse>-chap\u003CM>-*-chapter.tex` (M \u003C N). Course-level files that\nspan more than one chapter (a division plan, a shared study note) go directly in `lessons\u002F`, not inside any single\nchapter's subfolder. Only if the user names a different location, use that one.\nFigures are pgfplots code inside the `.tex`, so there are no image files. The chapter needs a TeX Live with `tcolorbox`, `pgfplots`, `enumitem`, `microtype` and\n`hyperref` (see the Dependencies section of `reference\u002Flatex-scaffolding.md`). Build with\n`bash \u003Cskill>\u002Freference\u002Fbuild-chapter.sh \u003Ccourse>-chap\u003CN>-\u003Ctopic>-chapter` from inside the folder; it copies `mastery-breaks.sty` and itself next to the chapter.\n\n## Which mode\n\n- No chapter exists yet for this subject, or the user wants one written from scratch →\n  **Mode A: author a new chapter**.\n- A chapter this skill already produced exists, and the user is pointing at a specific passage\n  that confused them (a quote, a screenshot, a description of \"this part\") →\n  **Mode B: confusion-driven update**.\n\nIf genuinely unclear which applies (e.g. the user wants both a new topic added to an existing\nchapter *and* a specific passage fixed), ask instead of guessing. These two modes have\ndifferent gates and a different blast radius.\n\n## Grounding dispatch\n\nBefore authoring or rewriting any technical content (a formula, a definition, a claim), check\nit's actually correct. If the target project has a vault (a `.vault\u002F` folder, or similar\nknowledge base), dispatch a `general-purpose` agent: find and read the vault's own schema file\nfirst, check for existing coverage there before falling back to a web search, and report back\nfindings\u002Fsources\u002Fgaps. Restate this guardrail verbatim in every such dispatch:\n\n> This pass is read-only. The agent must never write, move, or delete anything in the vault or\n> in any project file. If it finds something worth permanently recording, it reports that as a\n> gap for a separate, deliberate follow-up. It does not act on it itself.\n\nFor a quick fact-check mid-authoring, use the same dispatch with a narrower question instead of\na broad topic.\n\n## Mode A: author a new chapter\n\n**Language.** Write the chapter's own prose (titles, Legend, Theory, worked examples, exercises,\nsolutions, Reviews, Summary, Diagnostic check, figure and axis labels, source tags) in the\nlanguage the course's own input material uses (its lectures, homework, exams), not the language\nof the user's chat request. Names of curricula, exams, institutions and source files stay in\ntheir own language as proper nouns. If the input material is not clearly all in one language,\nask.\n\n1. **Ground the subject and take inventory.** Grounding dispatch (above) on the subject matter itself: what are\n   the real first principles, standard framings, common gotchas. Ask the user which folders hold the input material\n   (homework, practice sets, past exams, lecture notes, summaries) unless they already said, and also look in the project's vault for the\n   subject. **List every file** in those folders and **open every one completely** (a PDF page by page, nothing skimmed). Record file, type, page count and number of\n   question parts. Check [examples\u002F](examples\u002FREADME.md) too. The input material is the highest-signal source for which edge cases actually matter,\n   more useful than a generic treatment of the topic. Anything not opened is reported as a gap, never silently skipped.\n\n   **Find the course dependency baseline.** Before deciding Prior knowledge, search `lessons\u002F`\n   for course-level planning or baseline files such as `\u003Ccourse>-dependency-baseline.md`,\n   `\u003Ccourse>-chapter-division.md`, `\u003Ccourse>-*-chapter-estimate.md`, or similarly named files.\n   Read the relevant ones and treat them as the project-local source for the named baseline.\n   The skill remains generic; the course repository states what the baseline is.\n\n   **Find the earlier chapters.** Prior knowledge builds on the previous chapters of the same course, so before planning, look for them. Work out this chapter's\n   number N (from the request or the file name), then search the project for chapters M \u003C N of the same course: `\u003Cproject root>\u002Flessons\u002F`, the vault, and\n   the file name pattern `\u003Ccourse>-chap\u003CM>-*-chapter\u002F\u003Ccourse>-chap\u003CM>-*-chapter.tex` (see \"What this skill produces\" above). Read every one you find (its Theory titles, its Review terms and formulas, its Summary): that is what the\n   reader has already been taught and may be used without teaching it again. Record them in the inventory (chapter, file, Theory letters and titles). If N > 1 and no earlier\n   chapter is found, ask the user whether earlier chapters exist elsewhere before assuming none do. Chapter 1 has no earlier course chapter, so its Prior knowledge comes only from the named baseline.\n\n   **Study exemplars for method, not content.** If the user points to a previous chapter or PDF\n   whose pedagogy or visuals they like, inspect it and extract reusable method patterns: how\n   Theory moves from concrete picture to formula, how exercises escalate, how edge cases are\n   surfaced, and how the Diagnostic check mirrors the chapter. Do not copy subject-specific\n   claims unless they are part of the current subject and independently grounded.\n\n2. **Draft a plan and present it in chat**: a paragraph-by-paragraph (`§1`, `§2`, ...) outline,\n   each paragraph's Theory-block breakdown, and a rough exercise-tag count per block (how many\n   plain items, whether an R\u002FA\u002FD shows up, whether a Prior-knowledge block is needed first).\n   The default plan is a **Full Mastery** plan. It must include all in-scope source material and\n   all prerequisite bridges needed to make that material learnable from the baseline. A compact\n   plan is allowed only when the user explicitly asks for a compact chapter.\n   Also give the **dependency list**: for every Prior block, its source (the named course baseline, a baseline reference file when available, or the earlier chapter and its Theory letter,\n   which you found and read in step 1) and the Theory blocks\n   or exercises that use it before the chapter teaches it. A skill that nothing depends on is not Prior knowledge, and a skill the\n   chapter teaches itself is Theory (see \"What Prior knowledge is\" in `reference\u002Fpedagogy-cycle.md`).\n   Give an **edge-case and variation map** per Theory block: ordinary case, smallest nontrivial\n   case, shape\u002Ftype\u002Fdomain boundary, zero\u002Fidentity\u002Fempty or constant case where relevant,\n   symmetric\u002Fdegenerate\u002Fsingular or non-invertible case where relevant, sign\u002Fcorner\u002Flimit case\n   where relevant, and one common wrong move the chapter will explicitly inoculate against.\n   Irrelevant categories may be marked \"not applicable\"; unmentioned categories are treated as\n   unplanned, not implicitly absent.\n   Also say, per paragraph, which Theory blocks get a figure and which get a V exercise, and how many V exercises the paragraph has\n   (2 to 4, fewer only with a stated reason; see visual-intuition.md). For every block give the 3Blue1Brown source of the picture\n   (the search step \"Find the 3Blue1Brown material first\" in visual-intuition.md, done during step 1) and write the \"Visual sources\" table into `\u003Cname>-coverage.md`.\n   Also state the **Theory visual hook** for every Theory block: the concrete picture, table,\n   graph, diagram, trace, or tiny example that appears inside the Theory before the general\n   formula. If a block truly has no meaningful visual hook, say why and include a concrete\n   nonvisual representation instead.\n   Also give the Theory-block count per paragraph, and cut paragraphs by topic (see \"Where to cut\n   a chapter into paragraphs\" in `reference\u002Fpedagogy-cycle.md`; the sizes there are a guideline).\n   If the subject is clearly built on the target project's existing material, say what it\n   connects to and why.\n   Also list every question part in the input material and mark it in scope or out of scope, with a reason for each out of scope (the chapter or topic it belongs to).\n   Every in-scope part must end up in the chapter, in its own wording, with a solution that\n   matches the source solution's method and result (see \"Source questions and solutions are\n   mandatory\" in `reference\u002Fpedagogy-cycle.md`). Put the inventory and this coverage list in the plan, and write them to `\u003Cname>-coverage.md` next to the chapter.\n   Include a **no-omission declaration**: what would normally be tempting to skip, where it is\n   taught instead, and which optional tag lets a rushed reader skip it without removing it from\n   the chapter.\n\n3. **Stop and wait for the user's explicit go-ahead before writing anything.** Do not start\n   Mode A step 4 until they confirm the plan. This is a hard gate, not a formality. The plan\n   is cheap to redirect; 40 pages of LaTeX is not.\n\n**Supervised authoring: steps 4 to 8 are not one unsupervised dispatch.** Once the plan is approved, whoever is running\nthis skill (the main conversation, or an agent it dispatches to write) stays the orchestrator for the whole build and\ncheckpoints after every paragraph, even when the user has waived the step-3 plan gate for that run or asked for it to run\nstraight through without asking again. A single subagent authoring 40 to 200 pages unattended, however good its\ninstructions, drifts: it satisfies whatever is checked by a script and quietly lets whatever isn't checked slide,\nespecially the plain-English rules that have no automated check (a chapter authored this way once shipped with a third of\nits Drill exercises and a Legend that silently reverted to a stale, wrong template, both invisible until someone actually\nopened the PDF). The fix is not to trust the instructions harder, it is to look at the output before it compounds:\n\n- Dispatch (or resume) the authoring agent one stage at a time: the opening (title, Contents, Legend, Prior knowledge),\n  then one paragraph at a time. Tell it to build and report after each stage, per step 5 below, exactly as it already does\n  for its own progress log.\n- After **every** stage, the orchestrator itself (not a claim from the subagent's report) runs\n  `reference\u002Fcheck-chapter.py` on the chapter so far and reads all of its tables: EXERCISE RUN per Theory block (every\n  block just added needs D >= 3, per \"Exercise taxonomy\" in `reference\u002Fpedagogy-cycle.md`; a block under that is not\n  finished, send the same stage back before moving on), VISUALS per paragraph, THEORY BLOCK DENSITY, and LEGEND STRUCTURE.\n  A flag anywhere is not a note for later, it is the same stage's work, unfinished; resolve it before dispatching the next\n  stage, the same way a real editor reviews a chapter before the next one is drafted, not after the book is bound.\n- After the **opening** stage specifically, render the Contents and Legend pages to PNG and read them, don't just trust\n  `LEGEND STRUCTURE`'s text-level check. They are written once and never touched again, so a mistake here silently\n  affects every later stage.\n- After each **paragraph** stage, render and read at least one Theory box, the exercise run of one block, and one V\n  exercise's question and solution pages, the way step 7 below describes for the finished chapter, just done per stage\n  instead of only at the very end.\n- After each **paragraph** stage, run a completeness review against the plan's edge-case and\n  variation map. Every edge case promised in the plan must be either taught, drilled, placed in\n  C\u002FR, or explicitly deferred to a named later chapter. Do not silently drop edge cases to keep\n  the chapter short.\n- Only once a stage passes all of this does the orchestrator dispatch the next one. This costs more of the orchestrator's\n  own attention than firing one long instruction and waiting, that cost is the point: it is what catches a thin block or a\n  reverted template while it is a five-minute fix instead of a full rewrite.\n\n4. **Author one file**, `\u003Cname>-chapter.tex` (one source, two PDFs: with and without\n   solutions, see \"File structure\"), exactly per\n   [reference\u002Flatex-scaffolding.md](reference\u002Flatex-scaffolding.md)'s file structure and macro\n   set, exactly per [reference\u002Fpedagogy-cycle.md](reference\u002Fpedagogy-cycle.md)'s cycle and\n   presentation convention. Name the file `\u003Ccourse>-chap\u003CN>-\u003Ctopic>-chapter.tex` (for example\n   `ml1-chap1-mvcalc-chapter.tex`), with the chapter number right after the course prefix, so the\n   files sort in chapter order. If the target project already has a different chapter naming\n   convention (check its vault\u002Fdocs for other chapters this skill or a\n   predecessor produced). Every chapter opens with the title, Contents, locked Legend and Prior\n   knowledge in the house order;\n   see latex-scaffolding.md's \"Required opening\" section for the exact structure.\n\n   Author to full mastery depth by default. For each Theory block, include a concrete setup,\n   the visual or structural intuition, the formal statement, a worked example with every move\n   shown, then the T\u002FD\u002FV\u002FE\u002FC\u002FR run. Challenge exercises are not decorative: they protect edge\n   cases, unusual framings and common traps. A chapter with no Challenge exercises needs an\n   explicit user-approved reason.\n\n5. **Compile and verify.** Build both PDFs with `reference\u002Fbuild-chapter.sh` (it also lets LaTeX find `reference\u002Fmastery-breaks.sty`; three `pdflatex` passes each: hyperref\n   needs a second pass to resolve labels, and the table of contents needs a third to reflect page\n   numbers that shifted once it was inserted). Confirm zero errors (`grep -c '^!'` the log). Confirm no\n   undefined references. Render figure pages to PNG and look at them, in both PDFs. If `tcolorbox`\u002F`hyperref` aren't installed in the target environment,\n   see the Dependencies section of `reference\u002Flatex-scaffolding.md` for the\n   `tlmgr --usermode install` fix. This is a known, solvable hurdle, not a reason to fall back\n   to a different box design.\n\n   **Check the Contents fits on page 1** (design-system.md's \"Page 1 holds the title, the introduction and the Contents in\n   full\"), every time, not only for a long chapter: `pdftotext -layout -f 1 -l 1 \u003Cname>-chapter-answers.pdf -` and read off\n   the page number printed after \"Legend\" in the Contents listing. It must say 2. Any other number means the Contents\n   spilled onto page 2, shorten the introduction per design-system.md's order and rebuild before moving on.\n\n6. **Check the breaks** (rules in `reference\u002Fdesign-system.md`, \"Line and page breaks\"). In the questions PDF, scan every page break:\n   an exercise intro alone at a page bottom, a single part alone at a page top or bottom, a Theory paragraph cut in the middle, a solution\n   separated from its part. Look at `Overfull \\hbox` in both logs: each one is a long inline formula, turn it into a display. Grep the log for `has no \\newterm`: every `\\tm` key must be a term introduced in the Theory.\n\n7. **Visually spot-check the actual PDF**, not just the compile log: box seams (Theory and\n   Worked example should read as one continuous region with a subtle tone shift, not a visible\n   gap), any page break that lands inside a box (should be clean, no duplicated title), that\n   cross-reference hyperlinks actually resolve to the right place, and that the Contents (on the title page) lists every `\\frontsection` (Legend, Prior knowledge,\n   Summary, Diagnostic check). Also count plain exercises per Theory\n   block; fewer than 3 means go back and add more before calling a block finished, per\n   `reference\u002Fpedagogy-cycle.md`.\n\n   Then run the checks: `python3 \u003Cskill>\u002Freference\u002Fcheck-chapter.py \u003Cname>-chapter.tex \u003Cname>-coverage.md`. It lists the solutions that are too short for their\n   type (see \"Solutions: how extensive\" in `reference\u002Fpedagogy-cycle.md`: extend them or justify them) and checks the coverage file against the chapter: every\n   in-scope source question part appears, in its own wording, and each solution was compared against the source solution.\n   Also read the Summary and Diagnostic rows in the rendered Contents. The Summary must show\n   the Theory-letter snake, and the Diagnostic check must show its number pills. The Diagnostic\n   must mirror the chapter: at least one group per numbered paragraph, with fresh questions\n   covering the paragraph's core skills and at least one mixed\u002Fcapstone group when the chapter\n   culminates in source-style or exam-style problems.\n\n8. **Humanize pass** (see Overview) on the authored prose.\n\n9. Report back to the user for judgment. Don't declare success yourself: a clean compile is\n   necessary, not sufficient.\n\n## Token-efficient authoring exception\n\nWhen the user asks for a token-efficient run, checkpoint the opening and then batches of\ntwo or three numbered paragraphs. Use a one-paragraph checkpoint only for unusually risky\nmaterial or when the user requests it. After each batch, report only changed files, counts,\nhard failures, and unresolved questions, in at most ten lines.\n\nRun the checker after each batch, but show only its summary: exercise and visual counts,\nTheory density, opening\u002FLegend status, source-label count, and coverage failures. Treat\nmissing labels, missing Theory hooks, too few Drill families, malformed structure, coverage\nfailures, and LaTeX errors as blockers. Treat short-solution listings as review signals:\nalways fix bare answers and incomplete E\u002FC\u002FDiagnostic arguments, but do not mechanically\npad a compact atomic Drill or shape answer that already states its reason and result.\n\nRender Contents and Legend once after the opening, one Theory page and one V question\u002Fsolution\npair per later batch, and a selected-page final spot-check. Do not render every page unless\nan automated check reports a layout problem. If the user explicitly allows a multi-page\nContents, verify its order, readability, and links instead of forcing it onto one page.\n\n## Mode B: confusion-driven update\n\nA concrete procedure, not vague guidance. This is exactly what manual, successful fixes to a\nchapter's source look like in practice:\n\n1. **Locate the exact source location.** From the user's pointer (a quote, a screenshot, \"the\n   part about X\"), grep the chapter body for the nearest heading\u002Flabel or distinctive phrase,\n   then read that section directly to confirm you've found the right spot before touching\n   anything.\n\n2. **Classify the confusion into a concrete repair.** Don't default to \"explain it better in\n   chat\"; the fix belongs in the source, so the next reader doesn't hit the same wall:\n   - A fact or step was *used* but never *established* → promote it into a proper new Theory\n     subsection, built up from a concrete case, not asserted mid-derivation. (For example, a\n     derivation leans on \"a scalar equals its own transpose\" without ever having shown it.\n     The fix is a new Theory block deriving that fact from a 1×1-matrix argument, not a\n     one-line parenthetical.)\n   - A derivation jumped steps → expand it into more `align*` lines, one atomic move per line,\n     per the presentation convention.\n   - A prerequisite is missing → add a `refreshbox` (pale yellow, amber P badge) with a concise\n     recap plus a `\\Pbadge` exercise, right before its first use in the paragraph. If the gap is\n     big enough that a recap would not do, extend the opening Prior knowledge section instead.\n     Anything that is genuinely new material gets a full Theory block, not a refresher.\n   - A Worked example is hard to follow because it's doing too much at once → split it: end\n     the first stage, write `\\workedheading` again with \"Worked example (continued)\" for the\n     next stage, still inside the same `theorybox`, rather than cramming a multi-stage\n     derivation into one dense block. (`breakable` handles page-length overflow automatically,\n     so this split is about *clarity*, not page fitting.)\n   - Something was introduced with no motivation (\"why are we even doing this\") → add the\n     motivating sentence or two before the Theory box, or fold it into the box's own opening,\n     not as a floating unstyled paragraph between boxes. Floating prose outside any box is\n     itself a smell; every explanation lives inside a box.\n\n3. **Gate structural changes, not small ones.** Inserting a new Theory block or Prior-knowledge\n   subsection reflows the `\\exnum` stream after it, so confirm the plan with the user first, the\n   same way Mode A gates before writing. A small in-place expansion (more `align*` lines, an\n   added sentence) doesn't need a gate, just do it.\n\n4. **Edit the `.tex` source directly.** Never respond with only a chat explanation when the\n   confusion is about chapter content. The explanation belongs in the file future readers\n   (including a future you) will actually read. Note that `\\secref`\u002F`\\thyref` links elsewhere\n   in the chapter stay correct automatically after an insertion, since they're symbolic labels,\n   not hardcoded numbers.\n\n5. **Rebuild both PDFs** with `build-chapter.sh`, confirm zero errors.\n\n6. **Humanize pass** on the new\u002Fedited prose.\n\n7. Confirm the fix addresses what was actually asked, briefly, without re-explaining the whole\n   section back to the user. They asked about one spot, not a summary of the chapter.\n",{"name":5,"description":7},"main","4b7c39d99102c3553e0154cf6cd9d355474d2d5e","stations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter","https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations","https:\u002F\u002Fgithub.com\u002Fsalomepoulain","2026-11-05 19:59:44",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add salomepoulain\u002Fmakery-stations --skill write-mastery-chapter",{"tool":36,"command":37},"bunx","bunx skills add salomepoulain\u002Fmakery-stations --skill write-mastery-chapter",{"tool":39,"command":40},"pnpm","pnpm dlx skills add salomepoulain\u002Fmakery-stations --skill write-mastery-chapter","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002FSKILL.md",true,[44,50,54,60,64,70,74,78,82,86,90,94,98],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"codex-compatibility.md","REFERENCE","参考文档",6069,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Fcodex-compatibility.md",{"path":51,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":52,"sourceHtmlUrl":53},"examples\u002FREADME.md",1082,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Fexamples\u002FREADME.md",{"path":55,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":58,"sourceHtmlUrl":59},"reference\u002Fbuild-chapter.sh","SCRIPT","脚本",1118,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Freference\u002Fbuild-chapter.sh",{"path":61,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":62,"sourceHtmlUrl":63},"reference\u002Fcheck-chapter.py",16396,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Freference\u002Fcheck-chapter.py",{"path":65,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":68,"sourceHtmlUrl":69},"reference\u002Fcontents-mock.tex","OTHER","其他",7783,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Freference\u002Fcontents-mock.tex",{"path":71,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":72,"sourceHtmlUrl":73},"reference\u002Fdesign-system.md",14614,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Freference\u002Fdesign-system.md",{"path":75,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":76,"sourceHtmlUrl":77},"reference\u002Flatex-scaffolding.md",35171,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Freference\u002Flatex-scaffolding.md",{"path":79,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":80,"sourceHtmlUrl":81},"reference\u002Flegend-template.tex",5148,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Freference\u002Flegend-template.tex",{"path":83,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":84,"sourceHtmlUrl":85},"reference\u002Fmastery-breaks.sty",2522,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Freference\u002Fmastery-breaks.sty",{"path":87,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":88,"sourceHtmlUrl":89},"reference\u002Fpedagogy-cycle.md",34983,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Freference\u002Fpedagogy-cycle.md",{"path":91,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":92,"sourceHtmlUrl":93},"reference\u002Fpreamble-visual.tex",30482,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Freference\u002Fpreamble-visual.tex",{"path":95,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":96,"sourceHtmlUrl":97},"reference\u002Fvisual-intuition.md",15777,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Freference\u002Fvisual-intuition.md",{"path":99,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":100,"sourceHtmlUrl":101},"reference\u002Fvwo-wiskunde-b.md",2790,"https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-chapter\u002Freference\u002Fvwo-wiskunde-b.md",[103,110,117,124,131,138],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":19},"01M7CBGSD6SJZFDYW6S7RGZWDB","writing-for-agents","Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.","https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwriting-for-agents\u002FSKILL.md",[],[],{"skillNo":111,"name":112,"nameZh":6,"description":113,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":114,"categories":115,"keywords":116,"publishedAt":19},"01M7CBGJQA0MGJF0BX2DC4KWB9","writing-skills","Use when creating new skills, editing existing skills, or verifying skills work before deployment","https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-skills\u002FSKILL.md",[],[],{"skillNo":118,"name":119,"nameZh":6,"description":120,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":121,"categories":122,"keywords":123,"publishedAt":19},"01M7CBGBQB29Y6TZ0CVSCYYM6M","write-mastery-website","Turn a mastery chapter into a clickable website (one HTML page published as an artifact) that looks like the LaTeX PDF. Solutions sit behind a blue bar, hints open one at a time, every solution line has a \"why\" toggle, MC options can be checked, and each exercise has a finished circle and a flag. Use when the user asks for the website, HTML or clickable version of a chapter, or for \u002Fwrite-mastery-website. The chapter content itself is written with write-mastery-chapter.","https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwrite-mastery-website\u002FSKILL.md",[],[],{"skillNo":125,"name":126,"nameZh":6,"description":127,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":128,"categories":129,"keywords":130,"publishedAt":19},"01M7CBF2Z75S3T4NDHM1KFCCE6","wizard","Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.","https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwizard\u002FSKILL.md",[],[],{"skillNo":132,"name":133,"nameZh":6,"description":134,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":135,"categories":136,"keywords":137,"publishedAt":19},"01M7CBF0HFTPND5KRPT39BYZST","wayfinder","Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.","https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwayfinder\u002FSKILL.md",[],[],{"skillNo":139,"name":140,"nameZh":6,"description":141,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":142,"categories":143,"keywords":144,"publishedAt":19},"01M7CBEZ4KDXA6E0XFPJ8EWJEJ","wait-what","Stop. That last message did not land: re-pitch it.","https:\u002F\u002Fgithub.com\u002Fsalomepoulain\u002Fmakery-stations\u002Fblob\u002Fmain\u002Fstations\u002Fclaude\u002Fworkbench\u002Fpantry\u002Fskills\u002Fwait-what\u002FSKILL.md",[],[]]