Technical Book

---
name: technical-book
description: >
  Write, extend and maintain this technical book. Use when adding or revising a chapter, drafting
  front or back matter, adding chapter openers, summaries and bridges, keeping editorial voice and
  notation consistent, numbering figures and tables, resolving cross-references, refreshing dated
  claims, or producing the PDF. Triggers: "write a chapter", "revise the book", "draft the preface",
  "add chapter intros", "book architecture", "manuscript", "check what is stale", "refresh the
  model versions", "build the book".
---

# Technical Book Author

*Inside the Transformer: From Attention to Reasoning* is a finished 20-chapter technical book. This
skill maintains and extends it: keeping the through-line intact, the editorial voice consistent, the
numbering correct, and the dated claims fresh.

The book was converted from a seven-file modular knowledge base, which is why the guidance below
talks about deduplicating foundations and turning modular links into chapter references. That
conversion is complete, and the archive is not part of this repository. Apply the same thinking when
new material arrives from elsewhere.

## Core principle

**Preserve the content; rebuild the connective tissue.** The prose, worked numerical examples,
Mermaid diagrams, and the pedagogy — the three lenses (Geometric / Representation / Mechanistic),
the 🔑 plain-English boxes and 🔬 technical deep-dives — are the book's strengths. Keep them.

What a book needs and the source lacks:

- a book-level **preface** and "how to read this book" (the README is a repo README, not reader-facing);
- a **narrative arc** — chapter openers and closing bridges, so each chapter hands off to the next;
- **deduplicated foundations** (vectors, matrices, dot product, softmax, cross-entropy, KL, and
  tokenization/BPE are each taught from scratch in multiple files);
- **global cross-references** (source uses internal `§15`-style links and glossary `*Related:*`
  chains, not "as we saw in Chapter 3");
- clean **front and back matter** (strip per-file provenance footers and version blocks; replace
  the `99-references.md` bookmark dump with a real bibliography).

Edit for connection and consistency — not rewriting for its own sake.

## Working principles (author's decisions, 2026-09-12)

- **Publisher-independent for now.** Don't tie the manuscript to any publisher or their authoring
  format. (Manning already ships an *applied* *Transformers in Action* by Königstein, so if a pitch
  ever happens, differentiate on the explanatory / "how it really works" angle — don't mirror it.)
- **Content and pedagogy first; styling last.** Keep four layers separate and never let a later one
  contaminate an earlier one: (1) content & pedagogy — invest here; (2) source format — clean,
  portable Markdown; (3) production styling — fonts/shading/typography, kept *swappable* in a Pandoc
  reference-doc; (4) publisher specifics — deferred entirely.

## Source of truth

The chapter files are canonical: `frontmatter/`, `part-1/` through `part-5/`, and `backmatter/`.
Everything in `dist/` is a derived artifact. Never hand-edit it, and never commit it.

Inherit this repository's `CLAUDE.md` conventions rather than fighting them: hybrid math notation,
one H1 per file, figures generated by scripts, dated model callouts verified from vendor pages.

## Workflow

Work in phases. Do not convert everything at once, and confirm the architecture before drafting.

1. **Architecture first.** Agree the Part/Chapter map and manuscript layout before writing any
   chapter. See `references/book-architecture.md` — proposed structure, the source→chapter mapping
   table, and the deduplication plan.
2. **Front matter.** Draft the title page, the dated edition note, and the preface (who it's for,
   what you'll learn, the three lenses, how to read). Templates in `references/book-architecture.md`.
3. **Chapter by chapter.** For each chapter: strip the modular tells (footer, standalone H1/intro),
   add an opener (learning objectives) and a closer (summary + bridge to the next chapter), and
   convert internal `§`/`*Related:*` links into global references. Procedure and templates in
   `references/chapter-workflow.md`.
4. **Consistency passes.** Unify voice, notation, terminology, and figure/table numbering across
   chapters. Rules in `references/style-guide.md`.
5. **Back matter.** Assemble the glossary (Appendix A, from `01-terminology.md`), the
   specifications/evolution appendix, a cleaned bibliography, and an index.
6. **Produce.** Assemble and render deliverables — see `references/production.md`.

Track progress against the source→chapter mapping table so nothing is dropped or double-counted.

## Reference files

- `references/book-architecture.md` — Parts & Chapters, source→chapter mapping, front/back-matter
  templates, deduplication plan.
- `references/chapter-workflow.md` — per-chapter conversion procedure, opener/closer templates,
  cross-reference conversion, per-chapter checklist.
- `references/style-guide.md` — unified editorial voice, notation, lens/box conventions,
  figure/table/equation numbering, footer stripping.
- `references/production.md` — manuscript assembly and rendering to HTML/PDF/Word via the project
  build tools (`build-pdf.py`, Pandoc, WeasyPrint).
- `references/maintenance.md` — the freshness catalogue: every dated/volatile spot in the book and a
  web-verified refresh procedure to run when the field moves on. Invoke this when asked to "refresh",
  "update the model versions", or "check what's stale".

## Guardrails

- Follow `CLAUDE.md`: **hybrid math notation**, meaning inline Unicode, LaTeX `$$…$$` only for
  display equations that need it (fractions, matrices, multi-line), and worked numeric examples in
  fenced code blocks. Every diagram is a static SVG produced by a generator in `tools/figures/`, so
  edit the generator and regenerate rather than touching an SVG. Verify model version numbers from
  vendor pages, never from memory, and check every worked example in Python before committing. Full
  rules in `references/style-guide.md`.
- Don't invent content to fill chapters. If a topic is short (e.g. an individual training stage),
  balance chapter weight by grouping stages, not by padding.
- After large rewrites, run the prose-linter scanner:
  `python3 ~/.claude/skills/prose-linter/scripts/scan.py FILE.md --min-count 2`.
- The build is gated. `make check` runs the prose and structure gates, and `make pdf` refuses to
  produce a PDF when either fails. Do not work around a gate. Fix the finding, or enumerate an
  exemption in `tools/prose-allow.txt` or `tools/structure-allow.txt` with a reason.
- Freshness updates never silent-edit: web-verify against vendor pages (per `CLAUDE.md`) and surface
  a diff of proposed changes for the author to approve. See `references/maintenance.md`.