internals-book-volume

Internals Book Volume

This skill produces one finished volume per turn of a line-by-line neuroimaging-code teaching book, in the exact house style of the existing series. A volume is a ~30–40 page A4 PDF that dissects a representative program from a real codebase, line by line, teaching the language as it goes — with every listing quoted verbatim from a local clone at real line numbers.

The program lives under /Volumes/Niels_mac/Cpp_imaging. The master index of all series is NEUROIMAGING_SERIES.md; each series has its own <name>_book/SERIES.md roadmap.

Bundled resources — read these, don't re-derive them

• reference/conventions.md — the house style: the accuracy bar, the chapter arc, callout meanings, the ~30–40pp length standard, one-volume-per-turn cadence. Read it before writing any prose.
• reference/latex-pitfalls.md — the grep checklist that prevents build failures. Read and run it before every pdflatex.
• assets/preamble.tex — the shared design system, with {{LANGUAGE}} / {{SERIESLABEL}} placeholders. Used only when scaffolding a new series.
• assets/main.template.tex — the title-page + ToC skeleton, with placeholders. The basis for each volume's main.tex.

First: orient yourself

1. Read NEUROIMAGING_SERIES.md for the shared conventions and the series roster.
2. Identify which series the request is about and open its <name>_book/SERIES.md.
   • If the <name>_book/ directory and SERIES.md already exist → go to Write the next volume.
   • If this series has never been scaffolded → go to Scaffold a new series first, then write Volume 1.

Add a TodoWrite item per major step below so nothing is dropped.

---

A. Scaffold a new series (only if new)

Do this once per series, then immediately proceed to write Volume 1.

1. Clone the source, shallowly. Pick the layout from the roster:
   • Single monorepo → clone into <name>/.
   • Multi-repo ecosystem → one shallow clone per package into <name>_src/.

   git clone --depth 1 <repo-url> <name>/        # or <name>_src/<pkg>
   

   AppleDouble ._* files on this volume are harmless. If a clone already exists, reuse it.
2. Create the book directory <name>_book/ with:
   • common/preamble.tex — copy assets/preamble.tex and substitute the two placeholders: {{SERIESLABEL}} → e.g. AFNI Internals; {{LANGUAGE}} → the listings language and the Concept-box label (C, C++, Python, Matlab, R, bash). For a language listings lacks (TypeScript, GLSL), replace the language={{LANGUAGE}} line with a custom \lstdefinelanguage block and verify it compiles. Add the series' common type names to morekeywords=[2]{...}.
   • SERIES.md — the curriculum roadmap: a short intro (what the software is, why it shapes the teaching, clone+build commands) and a curriculum table with columns # | Title | Scope & exemplar | Key source files | Status, one row per planned volume, all ☐. Use the existing freesurfer_book/SERIES.md and afni_book/SERIES.md as models for tone and the part/section structure. The roster in NEUROIMAGING_SERIES.md gives the rough volume count and repo(s).
3. Add the series memory file. Create ~/.claude/projects/-Volumes-Niels-mac-Cpp-imaging/memory/<slug>-internals-book-series.md (a project-type memory) describing the series, and add a one-line pointer to MEMORY.md. Read MEMORY.md before writing and append only your line — a separate agent also edits it; never clobber.

---

B. Write the next volume

1. Pick the volume and find the exemplar

• In <name>_book/SERIES.md, take the first ☐ (planned) row. That row names the title, the scope, the exemplar program/function, and the key source files.
• Locate those files in the clone. Read them for real and find the exemplar function. Use grep -n and numbered reads so you know the true line numbers — these become the firstnumber values and the "line N" citations. This step is the work; the prose is downstream of actually reading the code.

2. Create the volume skeleton

Make <name>_book/volN_topic/ with:

• main.tex — from assets/main.template.tex, substituting the placeholders (volume number, cover title, subtitle, hook tying back to the previous volume, the "what this volume covers" paragraph, the verbatim-source footnote, and the \input{chapters/...} list). It \inputs ../common/preamble.tex and sets \renewcommand{\vollabel}{Vol.~N}.
• chapters/ — one file per chapter, numbered: 00_preface.tex, 01_orientation.tex, … , NN_appendices.tex.

3. Write the chapters — follow the arc and the accuracy bar

Follow the chapter arc and callout rules in reference/conventions.md: orientation → new language concepts → the data structure (in memory and on disk) → line-by-line walkthrough of the exemplar (the bulk) → call graph / data flow → appendices (glossary, "read any sibling yourself" method, hands-on, roadmap).

The accuracy bar is non-negotiable (full statement in reference/conventions.md):

Every lstlisting is copied verbatim from the clone, with \begin{lstlisting}[firstnumber=N] where N is the real first line number. Prose that cites "line N" must cite the real N. Never paraphrase, reformat, or invent code or line numbers. If you can't verify a line, pick a different exemplar — don't fabricate.

Aim for the ~30–40pp length standard through more real code explained carefully, not filler. Use concept / jargon / gotcha / tryit / takeaway boxes throughout.

4. Pre-build: grep the pitfalls

Before compiling, run the checklist in reference/latex-pitfalls.md against main.tex and chapters/. Fix every hit. The common killers: reserved TikZ keys (in/out/at/step/to/edge/node/grid/circle) used as node names; unescaped _ ^ % in \code{}/prose; math commands inside \code{}; sin/cos in TikZ plot coordinates; wide figures not wrapped in \resizebox; long \texttt{} paths in headings.

5. Build twice, then report

cd <name>_book/volN_topic && pdflatex -interaction=nonstopmode main.tex && pdflatex -interaction=nonstopmode main.tex

Two passes resolve the ToC and cross-references. If it errors, read the .log, fix, and rebuild. Sanity-check the result: the page count should be ~30–40 pp, and a suspiciously short PDF usually means a chapter didn't \input or an lstlisting wasn't closed. Report the PDF path and page count.

6. Update status — keep the roadmaps in sync

• In <name>_book/SERIES.md, flip this volume's status ☐ → ✓ (or ▶→✓).
• In NEUROIMAGING_SERIES.md, bump the series' progress count in the roster row (e.g. ✓17 → ✓18). Read before write.
• Update the series memory file's progress count, and (read-before-write) its MEMORY.md pointer line if the count is shown there. A separate agent also edits MEMORY.md — append/replace only your own line, never clobber others.

---

Notes

• Verify before you cite. The single most important habit is reading the real source and confirming line numbers with grep -n. Everything else is recoverable; a fabricated line number is not.
• Pedagogical order. Volumes assume the earlier ones. The preface should explicitly pick up where the previous volume left off, and the roadmap appendix should point at the next one.
• When a topic is too big, split it into two volumes and update SERIES.md, rather than cramming or thinning the teaching.