/technical-explanation

name: technical-explanation
description: Use when the deliverable explains a system, a process, an architecture, or a failure -- a bare "explain X", "how does this work", "what happened here", "qué es esto", "explicame cómo funciona", a status the reader must understand rather than execute, or the explanatory part of a README, a ticket, a deck, or a report. Loaded by the orchestrator when its answer explains, and by any specialist whose output explains.

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 container skills (`readme-writing`, `ticket-writing`, `diagram-builder`) 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.

| Mode | The reader arrives to... | It reads as | |------|--------------------------|-------------| | **Concept** | understand what something is and why it exists | a model: nouns, relations, consequences | | **Procedure** | do something, once, now | numbered steps with the expected result of each | | **Reference** | look one fact up | a table, scanned, never read start to end | | **Decision** | choose between options | the options, the criterion, the recommendation and its cost |

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:

| The idea... | Forms that shape produces | |-------------|---------------------------| | moves, diverges | flow (a path through stages), swimlane (a path across owners), timeline (a path across time), sequence (a path across parties, in message order) | | moves, converges | decision (paths that collapse into one choice), state (a thing moving between a fixed set of conditions) | | stands, diverges | architecture map (parts and the boundaries between them), before/after (two arrangements of the same parts) | | stands, converges | tree (a hierarchy under one root), dependency (what rests on what, down to one base) |

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