Technical Explanation

An explanation builds a mental model in the reader's head: what exists, how it connects, what happens, and why -- in that order, at the altitude the reader can hold, with one picture where a picture teaches faster than a sentence. This skill is the shared vocabulary for doing that: the four decisions taken before writing, the fixed order the model is built in, the two registers it is told in, and the drawing rules for the one picture a fenced code block can carry. Whoever produces an explanation loads it -- the orchestrator answering "explain X", a specialist writing the narrative of a README, the objective of a ticket, or the idea behind a deck. The register is human-register's; the container skills (technical-writing, ticket-writing, deck-builder, ghostwriting) own their format and continue from here; this skill owns what goes inside when the content explains.

The skill sits mid-flow. Upstream is a finding, a request, or a status already established by investigation; it never re-derives those. Downstream is a container that consumes the explanation as written -- so an explanation built in the wrong order does not stay a local defect: the README that embeds it teaches the wrong model, and the ticket that quotes it is misread by the stakeholder it was written for.

Core principle

The reader receives the model in the order they can hold it. A real identifier named before the reader has a place to put it is lost; a picture with fifteen concepts shown to a reader who can hold seven is noise; a reference table handed to someone who asked "what is this" answers a question they did not ask. So the explanation is built top-down -- a small picture of common nouns first, real components second, detail last -- and every element in it is chosen by a criterion the writer can state out loud: which kind of relation this idea is, how much the reader needs right now, what this sentence or this picture is FOR.

Step 1: Decide four things before writing

Nothing is written until these four are settled, because each one changes what gets written. They are decided in this order and take a minute.

1. Intent -- what the reader can do afterwards. Locate a failure, choose between two designs, operate a pipeline, trust a status, adopt a repository. An explanation with no intent explains everything at equal weight, which is the same as explaining nothing: the reader cannot tell which sentence to act on.

2. Mode -- which of four kinds of text this is. The four modes are distinct things a reader arrives for, and mixing them is how a "what is X" question gets a field reference for an answer.

A single deliverable can hold more than one mode (a README's narrative is a concept; its usage is a procedure), but one mode per section, never blended in one paragraph.

3. Representation -- chosen by criterion, never by lookup. Two questions decide which shape the idea has, and the answer is a shape before it is a form:

• Does the idea MOVE or STAND? A thing that moves -- a request, a change, a failure propagating -- is a path with a direction, and its picture reads along that direction. A thing that stands -- a structure, a hierarchy, a set of responsibilities -- is an arrangement, and its picture reads by position.
• Does the reading CONVERGE on one thing or DIVERGE into many? A convergent idea has one centre (one decision, one root cause, one component everything depends on); a divergent one has peers (several services, several options, several phases with nothing above them).

The catalogue of forms is a set of EXAMPLES of what those two answers produce, so the writer recognizes the shape they already chose -- not a menu to pick from:

When the two questions give an answer that the catalogue has no name for, the answer still holds: draw the shape the questions produced and call it what it is. When the two questions give no clear answer, the idea is not yet one idea -- split it before drawing it.

4. Density -- how much the reader needs now. The situation sets it, not the writer's thoroughness. Under urgency the order is fixed and the form is short: STATE -> PROBLEM -> ACTION -- what is the case now, what is wrong, what to do next -- and nothing before the state, because a reader in an incident reads the first line and acts. Normal density carries the model in the fixed order of Step 2. Deep density adds the why behind each connection and the alternatives that were rejected. The same truth appears at all three; density removes sentences, never precision. The rule comes from the disciplines that write for people under time pressure -- an aviation checklist or a control-room message is short because a long one is misread, not because the writer knew less.

Step 2: Build the model in the fixed order

The explanation answers four questions, always in this order, because each answer is the place the next one is stored in:

what exists  ->  how it connects  ->  what happens  ->  why
   (nouns)        (relations)          (the path)     (the reasons)

Naming what happens before what exists forces the reader to invent the parts; naming why before what happens gives reasons for events they have not seen. The order is not stylistic -- it is the order a model can be assembled in.

The model is told at three levels, and the reader always meets them top-down:

• Level 1 -- the picture. At most seven boxes, common nouns only: the CI machine, the cluster, the old system, the edge, the store. No real identifier appears here -- no namespace name, no service-account email, no file path, no flag -- because an identifier is a label on a box the reader does not yet have. If the picture needs more than seven boxes, it is two pictures or a level too low.
• Level 2 -- the real components. The same boxes, now named as they are: the workflow file, the controller, the namespace, the bucket. Every real name lands on a box that level 1 already placed, so the reader files it instead of meeting it.
• Detail. Identifiers, flags, configuration values, commands, the exact error text. Reached by a reader who wants it, never encountered by one who does not.

A reader may stop after any level and hold a true model. That is the test of the order: the explanation is true at every altitude it is cut at.

Step 3: The two registers

The user works in two registers, and the levels above are how both are served from one explanation rather than two.

Level 1 IS the plain register. It reads as a narrative, not an inventory: what we came to do, what we found, where we are, what follows. Its nouns are common ("the CI machine", not the service-account email; "the old system", not the namespace). Its findings are told by their CONSEQUENCE, not by their artifact -- "it would have destroyed something that is working", not the pasted output of the plan. It separates explicitly what is ours from what is inherited. And it closes with one sentence that holds the whole situation.

The technical register sits beneath it -- level 2 and the detail. It is the same truth at another altitude, never a vaguer one: the plain register does not simplify by omitting, it simplifies by choosing the altitude. A plain sentence that cannot be expanded into its technical counterpart without changing its meaning was not plain, it was wrong. Precision is never traded for vagueness at either level; what changes between them is which nouns are used and how much is said, not whether it is true.

The reader decides the register (human-register Rule 1), never the document type: a measurement an agent will consume stays in the technical register, and the same measurement a person reads to decide gets level 1 first.

Step 4: Drawing rules for the inline lane

The inline lane is ASCII inside a fenced code block: the only picture that reads identically on the web, in a terminal, and in a diff, and the only one that needs no tool to verify. It is the default lane; the rendered lanes in Step 5 are reached on request.

• Depict the mechanism, not its name. A box labelled "Kubernetes" teaches nothing; a box labelled "reconciles desired state" beside one labelled "holds desired state" teaches the mechanism. The picture shows what the parts DO to each other.
• Label the arrows. An unlabelled arrow is a relation the reader has to guess. --pushes image--> and --reads manifests--> are two different facts; --> twice is none.
• One arrow = one relationship. One block = one responsibility. A block that does two things is two blocks; an arrow that means "calls and also configures" is two arrows or one sentence.
• One term per concept, one idea per sentence. Do not call the same thing "the controller", "the operator", and "Flux" across three paragraphs; do not put a cause and its effect in one sentence when two sentences read faster. This is the controlled-language discipline of technical writing that must not be misread: a term with one meaning is a term the reader never re-resolves.
• Control flow and data/traffic flow are two drawings, never one. Who tells whom what to do, and what travels through whom, are different relations; a single picture carrying both is the crowded picture nobody can read.
• Only notation that reads without a legend. Boxes, │ ─ ▼ ►, and the tree marks └── ├──. No invented glyphs, no colour codes in text, no symbol whose meaning the reader has to be told. If a notation needs a legend it is not notation, it is a second thing to learn.
• A fenced picture stays within 80 columns. That is what makes it read identically on the web, in a terminal, and in a diff: a wider one wraps or scrolls in the terminal and the picture the reader sees is not the one you drew. A picture that needs more width is at the wrong level (lower it) or is two pictures.
• If a sentence says it faster, write the sentence. Two parts and one relation is a sentence, not a diagram.
• No decorative diagram. A picture that repeats the paragraph beside it costs the reader a second read of the same fact and asserts nothing. A picture earns its place by showing a relation the prose would take longer to state.

The picture obeys the levels: the level-1 picture holds at most seven boxes of common nouns; the level-2 picture is the same shape with real names.

Step 5: Continuing into a render lane -- on request only

An explanation written by this skill is complete as text. Two lanes render it when someone asks for a rendered artifact; neither is entered automatically, and the request is what opens them -- an explanation that would "look better as a deck" stays text until the user asks for the deck. The writer may OFFER the lane, in one line, when a rendered picture would teach more than the text ("this reads as a deck; say so and I build it"): offering names a capability the user did not ask for, entering it is the user's call, and nothing is built until they make it.

• deck-builder -- a deck of nested sections and components, authored in YAML. The explanation lowers into it by a fixed correspondence: a phase becomes a section in reading order; a step becomes a component ordered inside its phase; the path becomes one chip whose members cross the phase-sections; a disclosure level becomes a page. Arrows do not survive the crossing: the engine draws no edges, so every arrow of the inline picture becomes chip membership plus order, and a relation that only an arrowhead could express is stated in a component's text instead. That skill's toolbox.md carries every property and the forms a page declares, flow among them; the correspondence and what the engine rejects are in reference.md here.
• artifact-diagramming -- inline SVG inside an HTML page, for a single rendered picture rather than a deck. It is a host-provided skill, not a Gaia one; the drawing rules of Step 4 hold there unchanged (mechanism over name, labelled edges, one relation per edge), and it adds the mechanics that keep an SVG legible in both themes.

The lane is chosen by the reader's medium, never by the writer's preference, and the text explanation is kept -- the rendered artifact is a second telling of it, not a replacement.

Anti-patterns

• Fifteen concepts before a map. The reader is given every part at once and asked to assemble them; the level-1 picture of seven common nouns existed to spare them exactly that, and skipping it is how a correct explanation is not understood.
• Identifiers in level 1. A namespace name, a service-account email, or a file path in the first picture is a label on a box the reader does not have yet; it costs attention and stores nothing. Real names arrive at level 2, on boxes already placed.
• A reference dump answering a "what is X" question. The reader asked for a concept and received a table of fields: true, complete, and useless, because the mode was wrong. Mode is decided before writing (Step 1) so this cannot happen by momentum.
• Invented notation. A glyph, a bracket convention, or a colour code the reader must be taught turns the picture into a second subject. If it needs a legend, it is not the inline lane's notation.
• Decoration. A diagram that restates its paragraph, a box added for symmetry, an arrow drawn because the layout had room. Each costs a read and asserts nothing; the reader learns to skip pictures, including the one that mattered.
• One picture carrying two flows. Control and traffic in one drawing doubles the arrows and halves the legibility; the reader cannot tell "tells" from "sends".
• Vagueness sold as plainness. "Some things changed in the deployment" is not the plain register, it is the technical register with the facts removed. The plain sentence names the consequence ("the change would have deleted the database that is serving production") and the technical one names the artifact beneath it.

Where the rest lives

• examples.md -- three worked explanations in the DevOps register (a Kubernetes workload with control and traffic separated; a CI/CD pipeline at level 1 and level 2; a troubleshooting flow at urgent density) and each anti-pattern shown before and after.
• reference.md -- the field-level correspondence into the two render lanes, what each engine accepts and rejects, and the form catalogue with the criterion each form answers.