/write-manual

name: write-manual
version: 1.0.0
description: >
  Writes a long technical manual that explains one subject at one pinned version, from its purpose to each request and response.
  Every listing comes from an offline capture, every claim traces to a ranked source, and an audit must report TOTAL 0.
  Use it for "write a manual", "write a 101 manual for <subject>", "manual.json", "add a manual section",
  "build a capture kit", "audit the manual", or "pin a spec version and document it".
tags: [manuals, documentation, specifications, technical-writing, audit]

Write a manual

A manual explains one subject, such as a protocol, a file format, or a runtime, at one exact version. A lesson teaches a concept and moves on. A manual stays with one system until the reader can predict what it does in a case the manual never showed.

This skill gives the full method. It covers research, ranked sources, and a register of conflicts between sources. It also covers an offline capture kit, a fixed section shape, prose limits, and an audit that must report `TOTAL 0`. It works in any repository. Inside the AI Engineering from Scratch repo, the tooling already exists, and `manuals/a2a-101/` is the worked example.

When to use

• The reader must predict the behavior of one system, at one version, in cases you did not show.
• The subject has a specification, a schema, or a source tree that you can pin to a commit.
• You can run the subject, or a faithful stand-in, offline and record its requests and responses.
• The result is 60 to 100 pages with figures, and other people will maintain it.

When not to use

• You teach a general concept, such as attention or retrieval. Write a lesson instead.
• The subject has no version to pin, or changes every week.
• You cannot run the subject and cannot record its output. A manual without captures is an essay.
• You want a short how-to. A manual of fewer than about 15 sections does not need this shape.

Size of a 101 manual

| Item | Target | |---|---| | pages | 60 to 100 | | parts | 6 to 8, plus one reference part | | sections | about 25 | | figures | 30 to 40 | | outcomes in `manual.json` | at least 3 | | takeaways per section | exactly 1 block, with at least 2 items |

The worked example has 7 parts, 28 sections, 7 reference sections, and 31 figures.

Method

1. **Pin the subject.** Record the version, source URL, commit, release date, and verified date. 2. **Rank the sources.** List them in authority order: schema or proto, specification, project docs, reference SDK, capture kit. 3. **Vendor what the license allows.** Copy each quotable source unchanged into `research/sources/`, with its license file beside it. 4. **Write the fact brief.** Index every rule you will use by section and line number, in `research/`. See [references/research-and-sources.md](references/research-and-sources.md). 5. **Open the conflict register.** Give each disagreement between two sources an id (`D1`, `D2`, ...) as you find it. 6. **Build the capture kit.** Drive the subject offline and write deterministic files to `capture/out/`. See [references/capture-kit.md](references/capture-kit.md). 7. **Plan the contents from the specification.** Name each section after one thing the reader can find in the spec. 8. **Write `manual.json`.** Fill the pin, outcomes, palette, ranked sources, quote sources, capture commands, and parts. See [references/manual-json.md](references/manual-json.md). 9. **Write the front matter.** Title it "How to read this manual" and follow the order in "Front matter" below. 10. **Write one section at a time.** Use the section shape below. Cut every listing from a capture file. 11. **Draw each figure from a capture.** Follow the figure must-haves below and the sibling `blueprint-figure` skill. 12. **Build and audit.** Fix every finding until the audit prints `TOTAL 0`. See [references/audit.md](references/audit.md). 13. **Commit one section per commit.** Include its figures and the captures it adds.

Plan the contents from the specification

Build the table of contents from the names the specification uses, then decide what each part proves.

• **Front matter.** One document, `front.md`, titled "How to read this manual".
• **Part 1, the subject on one page.** Two sections: what the subject standardizes, then one complete exchange from a capture.
• **Middle parts.** One part per layer of the subject, such as discovery, data model, operations, bindings, security, and extensions.
• **Last part, implementation.** Build a client and a server. Test both with the official conformance tools. Explain migration from the previous version.
• **Reference part.** Method tables, objects, states, errors, a glossary, the sources and conflicts, and the figure index.

Each section title names one object, operation, binding, header, error, or extension from the specification. "CancelTask and terminal states" is a good title. "State machines" is not, because no specification defines an object with that name. Put a general idea in the section about the object that has it.

Front matter

`front.md` covers these topics, in this order:

1. Who the manual is for, and what they can do after it. 2. How it was made, with the ranked sources table. 3. The capture kit. 4. The conventions: citation forms, listing cuts, and id shortening. 5. A first run that the reader can do offline. 6. How the parts are ordered, as an empty `parts` block. 7. Colour in figures, as an empty `palette` block. 8. Figure 0.1, which teaches the arrow and colour grammar of this manual.

Section shape

Every section file follows this order. Reference sections and the front matter need a thesis and a sources line, but no outcome sentence and no takeaways.

1. `# Title`, with the name the specification uses. 2. `> Thesis`, directly under the title: one sentence of at most 30 words, the claim the section proves. 3. An opening paragraph that starts from a concrete situation the reader has been in. 4. The sen