| name | format-layout-diagram |
| description | Draw the layout of a memory or wire format that already exists in code — a
byte anatomy of one encoded instance, the per-variant conventions of a shared
encoding, or the linkage between blocks. Use when asked to "diagram the
format", "show the byte layout", "draw the header", "picture the on-disk
structure", "explain the encoding", or when a format reference, design
record, or pull request needs a figure of a structure a reader cannot hold in
their head. Beta — the conventions come from one format in one repository, so
record friction and confirmation through `engineering-journal`. Symptoms that
this skill applies: a byte grid drawn by hand from a specification, a figure
whose offsets no longer match the encoder, a byte grid routed through a graph
layout engine, a figure that cannot say whether it shows what ships or what
is planned, or a figure that looks right in a browser and breaks in the
rasterizer that publishes it.
|
Format layout diagrams
A layout figure answers a question prose answers badly: what occupies which
bytes, and what addresses what. Prose carries a sequence; a layout is a shape
with addresses, and re-deriving it from sentences is the work the figure exists
to remove.
This skill is the third in a family and inherits its principles:
derive-never-draw, fail-loud, verify-the-rendering. architecture-diagram owns
what exists and what contains what; dataflow-diagram owns what moves where.
When the question is "which byte is that field in", it is this one.
What this is, and what it is not yet
Treat this skill as beta. Its conventions come from one binary collection
format in one repository, whose figures were built without a skill and whose
author proposed this one afterward. Three rules below are that author's, stated
in their own words; the rest is inference from the artifacts and carries less
weight. When one fights your format, the override and its reason are the most
valuable thing the effort produces: record it through engineering-journal.
Three rules
Position is the byte offset. No layout engine. In a byte grid the x-axis
is the address, so nothing may be free to move a cell. Emit the drawing
directly, with integer geometry and fixed ordering. Routing a byte grid through
a graph layout engine was tried and abandoned: clusters and edges moved cells,
which broke the one claim the figure exists to make.
Spans come from golden fixtures decoded by the shipping codec. Not from the
specification, and not from a decoder written for the figure. A second decoder
is a second source of truth — one was written, then deleted for that reason.
The generator walks a frozen test fixture through the production decoder and
aborts when any drawn span disagrees with the bytes.
Freshness is a deterministic regenerate-and-diff on the artifact readers
see. Not a checksum of the source, and not a promise to remember. Because
emission is deterministic, regenerating and diffing covers exactly the file a
reader opens.
The derivation contract
A derived figure is produced by a program that fails loudly rather than drawing
something plausible:
- Assert every span against the bytes. A length that does not match, a
count that does not match the walk, a stored offset that does not land on the
element it names — each aborts, naming what disagreed.
- Re-encode and compare. Decoding proves the reading; re-encoding each
decoded value and comparing bytes proves the figure's labels describe a value
the codec would produce. It catches a tier table that has drifted from the
encoder, which decoding alone does not.
- Check the frame, not only the content. Cells past the drawing bounds are
an abort, not a cosmetic problem. A figure that silently clips is worse than
one that refuses to render.
- Freeze the instance. Draw a fixture the tests already pin, and name it.
- State the regeneration command in the artifact's own header and in the
provenance table, so the next person changes the generator rather than the
output.
Choose the instance for coverage, not size: the smallest encoding that
exercises the header, at least two entries, at least two width tiers, and every
cross-reference the format defines. A one-entry example teaches the header and
nothing else.
Source format follows what the figure claims
A byte grid and a relationship schematic are different kinds of claim, so they
keep different sources. Record the choice in a provenance table beside the
figures — one row per figure, naming its source, its regeneration command, and
what it asserts.
- Byte anatomy — generated, emitted directly, no render step. The committed
artifact is exactly what the generator produced. A render step between
generator and artifact reintroduces a layout engine's freedom over a grid
whose positions are addresses.
- Relationship schematic — graph source, rendered. Chaining, linkage,
shipped-against-reserved. Here a layout engine is correct: the claim is what
connects to what, not where anything sits. The graph source is the diffable
artifact; its render depends on the renderer's version and is refreshed on
edit.
- Hand-authored snapshot — direct drawing, no generator. Variant
conventions and other design claims that no code produces. Date it and name
the review it came from, because nothing will detect its drift.
A generated figure may not draw what does not exist. A schematic may, if the
unbuilt half is visually distinct — dashed for reserved, solid for shipped —
and the caption says which is which.
Verify the rendering, not the markup
A figure that is valid and unreadable has failed. Rasterize the committed
artifact before committing it, with the same tooling the publishing host uses.
Two defects found this way in one figure, neither visible in a browser: a
double hyphen inside an XML comment, which is illegal and rejected by strict
parsers; and a root style setting maximum width with automatic height, which
collapsed the canvas to zero height in the rasterizer while looking correct
locally.
Rasterizing proves the figure drew; it does not prove the figure is balanced.
A bracket label nearer a neighboring span than its own, a two-line label
centered by its first baseline, an offset arrow attached wherever the code
reached first — each is inside the frame and each is what a reader sees
first. architecture-diagram carries those placement rules as a set; a byte
grid inherits them the moment it emits its own geometry, which this skill
requires. And when the rasterizer a check depends on is unavailable, say so
and name what stood in for it — markup validity, a deterministic regenerate
compared by hash, bounds and collision checks, a reviewer reading the
committed artifact. A check skipped without that record reads afterwards as a
check passed.
Also: emit fixed ink over an opaque ground rather than colors inherited from
the page, because a host that embeds the figure as an image strips that
context. Give the figure a text alternative twice — an accessible label inside
it, and prose beside it stating the same claim.
A default visual language
Adopt wholesale; override with a reason.
- One cell per byte, fixed width, in offset order, value in hex. Bytes are
the unit even when fields are wider, because the reader's question is "which
byte".
- Fill by role, not by field — header, tag, payload, trailer — reused
across every entry. Four colors learned once beats one per field.
- An offset ruler under the cells, at reduced opacity: a reference the eye
returns to, not content.
- Brackets above for spans, staggered when labels would collide, each
carrying the field name and its decoded value. The value is what lets a
reader check the figure against the bytes.
- An arrow for every stored offset, from the field to the element it
addresses. This is the part readers remember, because it turns a number in a
header into a place in the picture.
- A caption that states the claim, not the contents. "The tail offset
points at the last entry's first byte, so tail access is constant time" earns
its space; "diagram of a block" does not.
Boundaries
architecture-diagram owns structure; dataflow-diagram owns movement. A
reader asking which byte holds a length is asking neither.
technical-prose owns word choice in captions and surrounding prose, including
its default of American spelling. Field names, type names, and byte values are
untouchable — they are names, and a figure that renames them to read better has
stopped describing the format.
engineering-journal owns the durable record of why a format is shaped as it
is. The figure carries the shape; the entry carries the argument.
Known dead ends
- A graph layout engine for a byte grid. Clusters and edges move cells,
which breaks position-is-offset. Emit directly instead.
- A second decoder written to drive the figure. It is a second source of
truth, and the two drift. Derive through the shipping codec.
- Drawing the grid by hand from the specification. Correct on the day it is
drawn, wrong at the first encoder change, with nothing to detect it.
- Freshness by convention. "Regenerate when the format changes" is a
promise, not a check. Until the regenerate-and-diff runs somewhere, assume
the figure is stale.
- One figure for the shipped and the planned shape, undifferentiated.
Readers act on all of it as though it exists.
Red flags
- A byte grid whose cell positions came from a layout engine.
- A byte grid with no generator, or a generator with no abort path.
- A generator that decodes but never re-encodes to compare.
- A figure with no provenance row: no source, no regeneration command, no
statement of what it asserts.
- A committed artifact that is a render of a generated intermediate rather than
the generator's own output.
- Offsets that no longer match the encoder, with nothing that would have caught
it.
- A fixture that is not the one the tests pin.
- Cells past the drawing bounds, silently clipped.
- A bracket or arrow label nearer a neighboring span than the one it names.
- A rasterization check skipped for unavailable tooling, with no record of
what stood in for it.
- An artifact committed without being rasterized the way the host will.
- A figure that inherits its colors from the reader's theme.
- A schematic that omits which half is reserved.
- A caption that names the contents instead of stating the claim.
- A field name rewritten in a label so the figure reads better.
