Technical manual

You are writing a reference book an engineer keeps open while writing a parser, debugging a crash, or deciding how to configure a writer. It runs from the first idea down to the exact bytes or stored rows. The method has one rule:

Nothing is written from memory. Every claim traces to a pinned source or a captured artefact, and every figure is drawn from that same data.

What that produces:

• Pinned, ranked evidence. One subject at one commit. Code outranks the spec; where they disagree, the book says so.
• The real thing on the page. Real hex, real headers, real stored records, cut from captures and decoded by hand, then checked against the reference implementation.
• Figures as data. Byte strips, hex walks, sequence diagrams and bar charts generated from captures, about one every two pages, in one colour code that holds for the whole book.
• Plain, exact prose. Short declarative sentences with numbers and names in them, and a Sources line closing every section.

The output is a Letter-size PDF in a fixed house style (cream paper, dark part openers, Manrope / Source Sans 3 / Source Serif 4 italic / JetBrains Mono), typeset with Paged.js from HTML fragments by the kit in assets/kit/.

Files in this skill

Prerequisites

Check these before Phase 0, and ask the user to install anything missing before the research starts. Do not discover a missing tool at Phase 6.

Without pdftoppm the build still writes the PDF but skips the page images, and you cannot do the visual check in Phase 6. If the user declines to install it, say in the hand-over that the pages were not looked at.

Workflow

Do the phases in order. No prose is written before phases 1–3 exist on disk: the book is a rendering of the research folder, not something written alongside it.

Phase 0. Scope card

Settle these and write them at the top of research/OUTLINE.md:

• Subject and pin. package@version and repo@commit, or spec@commit plus the implementations you will read, and the date read. Default to the latest release.
• Reader. One paragraph: what they already know, and what they have not read.
• Promises. 4–7 "After this book you can…" capabilities. Every part serves one.
• Specimens. The 3–12 real files or runs the book dissects: public and recognisable where possible, one small enough to show whole, one large enough to show scale.
• Angle. The job the reader's team has (e.g. reading the format over HTTP), if any. It earns its own part and the "why it matters" callouts.
• Theme. "warm" (orange on brown-black, dark cover) or "cool" (blue on navy, paper cover).
• Size. Let the subject decide. A full manual is 6–10 parts, 40–55 sections, 100–190 pages and 60–80 figures; a small format honestly covered may be 40–80 pages. Every section starts a new page, so a point that will not fill most of a page goes under an h2 in a neighbour.

If the user gave only a topic, propose the card in one message and confirm it before the research, because research is the expensive part. If they are not there to answer, take the card as proposed and say so at the top of the hand-over.

Phase 1. Research folder

Copy the kit and set up the folder laid out in references/grounding.md §1. Clone each repo at its pin; build or install the code you will run from that same commit and record its version. Read the spec end to end and the code that implements each part, writing research/notes/<part>.md as claim → file:line, with quoted rules, defaults as found in source, and every spec–code disagreement. Fill research/SOURCES.md as you go. With subagents, split the reading by part or by implementation and ask for evidence only (§4).

If the environment cannot reach the repo or spec, stop and tell the user what you need. A manual in this style that is not grounded is worse than none.

Phase 2. Capture kit

Write scripts in research/capture/ that produce every artefact the book will show: real headers by range request, decoder traces over the specimens, storage dumps, event logs, crash and kill runs, malformed inputs fed to the reader, measurements. Each writes JSON (for figures and bound values) and TXT (for listings) into research/captures/; research/capture/run.sh regenerates all of it; capture/README.md says which values are stable across runs. If published files cannot be fetched, write specimens with the reference implementation, keep the script, and say so in the front matter and the not-verified list. Parse each specimen two ways (your script and the reference library) before drawing it.

Phase 3. Outline

Write research/OUTLINE.md in the format of references/grounding.md §8: for every section its number, title, deck (the section's claim), the promise it serves, its sources, its figures with their data source, and its callouts. Order the parts by one stated principle: why it exists → the mental model → the layout byte by byte (or record by record) → what it carries → the hard core with worked examples → how it is written and by whom → how it is loaded, run or read in practice → the reader's angle → Reference. For a format the spine is the file from outside in; for a library it is one request traced through the layers, then each layer. Plan at least one figure per section and about one per two pages overall, choosing each figure's kind from references/figure-catalog.md. Plan the Reference part from the patterns in references/style-samples.md: structures and enums for a format, the user-facing surface (flags, settings, env vars, keys) plus a "Documentation versus code" table for a library.

Phase 4. Write

One file per part. Follow the section anatomy and voice below, references/markup.md, and the calibration excerpts in references/style-samples.md. Bind every captured number with data-value and every shown output or excerpt with data-include, so prose cannot drift from the data. Cite inline with <cite> at the end of the clause. Log each claim that is not obvious from a single cited line in research/CLAIMS.md. Close each section with its Sources line.

Phase 5. Figures

Generate data figures with kit/figs.py (hexdump, strip, bars, sequence, excerpt), one small script per figure in research/figs/, pulled in with <!--#include research/figs/name.html-->. Hand-place flows, structures and state machines in SVG with the kit classes. A figure a capture could not produce is tagged illustrative and its caption says so. Build the cover plate last, from a real specimen: an exploded or annotated artefact with numbered callouts and a key. Look at references/exemplars.md first.

Phase 6. Build, look, audit

Build, fix every problem the build prints, then read the page images: overflowing figures, orphaned headings, half-empty pages, illegible or misplaced labels, a colour used off its meaning. Fix layout by resizing or splitting a figure, reordering blocks, or merging a thin section into its neighbour; never delete a sourced fact to make a page fit. Then run the claim audit (references/grounding.md §9) with a reviewer that did not write the book, and fix, delete or mark unverified everything that fails.

Phase 7. Hand over

Give the user the PDF, the pins, and the not-verified list in two or three sentences. Keep research/ with the manual; it is the proof.

Grounding rules

1. Every section ends with a Sources line naming the spec sections, source files (with line ranges or function names), captures and scripts it was written from. The build refuses sections without one.
2. Never invent bytes, offsets, ids, timings, sizes or outputs. If it is shown, a capture produced it. Illustrative figures are labelled illustrative.
3. Pin and print the revision. Commits shortened to 7 characters, in the front matter, the Sources table and beside every excerpt.
4. Quote, do not paraphrase, when wording carries weight, with the location.
5. Defaults are the values in source at the pin, not the documentation's. Say when they differ.
6. Others' measurements are quoted exactly and attributed; your re-runs appear beside them, never instead.
7. Say what kind of fact it is. "The spec says", "ggml checks", "every specimen has", "an estimate from the constants, not a documented figure".
8. Disagreements are features. Spec versus code, writer versus writer, docs versus behaviour: state both, cite both, follow the code.
9. Unverifiable claims are deleted, or kept in an Unverified callout with the reason, and collected under "Not verified, and therefore not claimed" in the Reference part.
10. Code excerpts are real, cut from the pinned checkout with path, lines and commit; cuts are marked … and the note beneath says what was cut.

The book

manual.json drives the build:

{
  "title": "GGUF",
  "short": "GGUF",
  "slug": "GGUF",
  "edition": "Hub Engineering Edition · 2026.09",
  "description": "A source-grounded guide to the single-file model format: the byte layout, the metadata conventions, tensor naming, every quantization block, sharding, loading, and reading headers over the network.",
  "author": "Prepared for …",
  "theme": "warm",
  "cover": { "plate": "cover.html" },
  "front": "00-how-to-read.html",
  "parts": [
    {
      "title": "Orientation",
      "short": "Orientation",
      "deck": "Why a model became a single self-describing file, and what that decision still costs.",
      "file": "01-orientation.html"
    },
    {
      "title": "Reference",
      "number": "R",
      "deck": "Tables to keep open while writing a parser.",
      "file": "r-reference.html"
    }
  ]
}

theme is "warm", "cool", or an object { "preset": "cool", "accent": "#…", "accentInk": "#…", "dark": "#…" }; cover.style ("dark" or "paper") overrides the preset's cover. The build generates the cover frame, Contents, part openers with their mini-contents, section and figure numbers, cross-reference page numbers, running heads and the index of figures. You write the cover plate, the front matter and the sections.

• Cover plate. A hero figure made from a real specimen that teaches something on its own: magic bytes set huge over the first hex rows, or "Plate I", an elevation of the file with a numbered key. The description is one sentence listing what the book covers.
• Front matter (00, "How to read this book"): one <div data-title="How to read this book" data-deck="…"> with h2 subheads and a Sources line. Figures are not numbered here, so use tables and .swatches. It covers what the book documents and at which revision; who it is for and the promises; how it was made (sources ranked, specimens table, capture kit); conventions (offsets, types, units, cross-references, the colour code, how measured and unverified claims are marked); one line per part. For a library, a first example the reader can run.
• Parts. A title of two to four words and a deck stating the part's idea.
• Reference ("number": "R"): lookup tables that restate the book (every field, enum, key, default, error), a Glossary, "Sources and versions" (source · revision · used for) with the not-verified list, and <div data-generate="figure-index"></div>.

A section

<section
  class="sec"
  id="what-readers-check"
  data-title="What readers check"
  data-deck="The format has no checksum, so every guarantee comes from a reader that refuses bad input. The readers differ in what they refuse."
>
  <p>
    Lede: what this section establishes, what you will be able to do with it,
    and the order it goes in.
  </p>
  <figure class="fig" …>…</figure>
  <h2>ggml: structural validity</h2>
  <p>… <cite>src/gguf.cpp:228–420</cite></p>
  <p class="sources">
    ggml src/gguf.cpp gguf_reader (:228–420), gguf_init_from_file_impl
    (:440–910); research/captures/malformed.json
  </p>
</section>

• Title. A plain noun phrase or claim: "The fixed header", "Why the tokenizer dominates the header", "Reading starts at the end", "Worked example: a real Q4_0 block". Never a pun or question.
• Deck. One or two italic sentences giving the finding, concrete enough to be wrong.
• Lede. What the section covers and in what order ("This section lists…, and closes with…"). No scene-setting. The build sets it a size up.
• Subheads (h2) each make one point: "Field by field", "Endianness is inferred, not declared", "What is not stored", "Who writes it", "What it costs", "Measured".
• Body. A paragraph or two, then a figure, table or listing; rarely more than half a page of unbroken prose. Ruled .items for parallel points.
• Worked examples are their own sections: fetch real bytes (show the command), draw them, decode step by step with the arithmetic, then the short script that checks against the reference library.
• Close with a callout where one earns its place, then the Sources line.

Voice

Write like an engineer who has read the source and is telling a colleague what is there.

• Declarative, present tense, mostly short sentences. "Nothing in the file points backwards and nothing points to the header, so the first three regions can only be read sequentially."
• Numbers with units and names in code font, constantly: fields, functions, constants, error strings. "11,906 bytes for 201 tensors, about 59 B each."
• Mechanism, then consequence. "Arrays record an element count but not a byte length. That single decision shapes …"
• Say what the thing does not do and what it costs ("What the format deliberately does not do").
• "You" only when giving the reader something to do or decide.
• No hype, hedging, warm-up, rhetorical questions, "let's", or summaries that repeat the section. If a sentence has no number, name or mechanism in it, cut it. Nothing is powerful, robust, seamless, simple or elegant; show the measurement.
• First use of a term defines it in passing, and it goes in the Glossary. One term per thing, the name the source uses.
• Cross-reference instead of repeating: <a class="xref" href="#mmap">the loader</a> prints as "the loader (p. 76)".

Figures

At least one figure, table or listing in every section and a numbered figure about every two pages. A figure shows what prose cannot: proportion, position, order, correspondence.

• data-title is two to four words; data-tag gives kind and provenance (byte layout · real file, measured · log scale, spec § 3.2, sequence · tensor.rs:302–377, illustrative); the kinds are in references/figure-catalog.md.
• The caption opens with a bold finding, a sentence the reader could quote, then says what was drawn from which specimen or capture. The index of figures lists these findings.
• One colour code for the whole book. Assign each of k1–k7 one meaning in the front matter (for a format: header, metadata, index, data…; for a system: host, model, storage, task…). k0 grey is padding, unused or elided; hatch is wasted or skipped bytes. Arrow kinds (call, return, async, error, data, context) also keep one meaning each. In sequence diagrams a colour may instead mark the participant, as long as the front matter says so.
• Real values in the boxes: actual sizes and offsets from a named specimen.
• Text never overlaps or leaves its box. Prefer the generators, which lay out from data.

Build

cp -r "<this skill's folder>/assets/kit" kit
(cd kit && npm install)                        # pagedjs, fonts, highlight.js, playwright-core
node kit/build.mjs manual --png                # -> manual/<slug>-Technical-Manual.pdf, manual/build/pages/*.png
node kit/build.mjs manual --png --dpi 130      # sharper pages for proofreading small type

To check the install, copy references/example beside the kit and run node kit/build.mjs example --png: 19 pages, no problems, and page images in example/build/pages/. The build needs a Chromium; it tries Playwright's, then PLAYWRIGHT_BROWSERS_PATH, CHROME_PATH and common install paths (npx playwright-core install chromium fetches one). --png needs pdftoppm (see Prerequisites).

The build prints page, section, figure and bound-value counts, then every problem: sections without sources, decks, or any figure, table or listing; figures without a finding or provenance; listings without a source; missing captures or paths in data-value and data-include; broken references; blocks wider than the page or split across pages; half-empty pages from an oversized block; a few lines spilling onto a new page; labels that do not fit their box; overlapping SVG labels; filler words. Notes follow (figure density, illustrative figures). Fix every problem, then read the page images yourself: the build cannot see a wrong number or a label on the wrong box.

Before you hand it over

• research/capture/run.sh regenerates every capture and generated figure, and the book rebuilds clean afterwards.
• Every number in the book is bound to a capture or cited to a line.
• The claim audit ran, and every failed claim is fixed, removed or marked unverified.
• Every promise in the front matter is served by a part.
• The colour and arrow codes mean the same thing on page 7 and page 107.
• Spec–code differences are stated where they occur; pins are printed in the front matter and the Sources table; the not-verified list exists and is honest.
• You have looked at every page image.