/technical-writing

name: technical-writing
description: Use when writing, rewriting, cleaning up or updating a document people will read later, without the conversation that produced it -- a README (repository root, a folder that holds one kind of thing, a shipped template), a runbook, a pull request body, a report or status document, a CHANGELOG entry. Triggers -- "escribe el README", "actualiza el README", "el README está desactualizado", "falta el README de esta carpeta", "write the README", "the README is stale", "write a runbook", "redacta el PR", "write the PR description", "arma el informe", "write the status report", "add a changelog entry", or a drift report flagging a README as stale.

Technical Writing

Technical writing produces the documents people open later, alone: a README, a runbook, a pull request body, a report, a CHANGELOG entry. Each is the mental model its reader needs before they touch, review or adopt the thing it describes, and each is read without the conversation that produced it. The register is `human-register`'s and the explanatory parts follow `technical-explanation`; this skill owns the documents themselves -- which one the situation calls for, its sections in order, and the one section in each that carries the weight.

Four things hold for every document here, stated once:

• **Every tree is annotated.** One line per entry, giving the reason that entry exists. A bare tree adds nothing over `ls`.
• **Every link is relative.** An absolute link points at one host, one account, one branch; it breaks in a clone, in a fork, and on every branch it was not written on.
• **Every flow is plain text** -- numbered steps and simple `->` arrows in a code block. Never mermaid, never any format that must be rendered to be read. A rendered diagram can only be verified by looking at it rendered, which needs a tool that may not be installed; one shipped recently that nobody could validate for exactly that reason. Plain text reads identically on the web, in a terminal, and in a diff.
• **Nothing names the machinery that produced it.** No agents, tools, tiers, approvals, task ids or plan labels: the reader is a person who was not there, and the process is not their document.

The user's rows apply on top -- the heading set a repository or team expects, the language everything versioned is in, what a client's document never names -- read from the rows that reach the writer, never restated here.

Step 1: Name the door

The door decides everything after it. Five documents, five readers, five questions the reader arrives with:

| Door | Who is reading | The question they arrive with | |------|----------------|-------------------------------| | **README, repository root** | Someone evaluating -- they may clone it, adopt it, inherit it, or walk away | "Does this serve me?" | | **README, component folder** | Someone about to add, change, or remove something in that folder | "What is this wired to, and what do I break?" | | **README, shipped template** | Whoever receives what was generated | "What is mine now, and what do I have to do?" | | **Runbook** | Someone doing a rare, costly task by hand, now | "What exactly do I run, and how do I know it worked?" | | **PR body** | A reviewer who was not present while the change was made | "What changed, why, and how do I know it is safe?" | | **Report or status** | Someone deciding or acting on where things stand | "What is the situation, what is grave, what do I do?" | | **CHANGELOG entry** | Someone upgrading, or finding when a behavior changed | "What is different for me in this version?" |

The root of a client's Terraform repo, a service, a library, a CLI -- all one door: repository root. A folder inside a repo that holds one kind of thing -- `migrations/`, `modules/`, `components/`, `services/`, `agents/` -- is the second. A README that travels inside generated output, into a repo its author will never see again, is the third. A repo root and one of its folders are two separate passes, each through its own door. Naming the door wrong is the expensive failure: the work is done correctly and the artifact is the wrong one.

**The one collision worth a tie-breaker: a generated repo that someone then lives in.** It was rendered by a generator, which points at the template door, and it is somebody's repository root, which points at the first. The axis that separates them is the reader's relationship to the thing, not who wrote it. A shipped template's reader did not choose to be there and has one thing to do, once -- its README is a handover note that expires when the last step is done. A repository root's reader is deciding whether to take this on and then lives with it -- its README keeps answering questions long after the first day. A generated client repo whose owners will work in it for a year takes the root door, generator or not.

Step 2: Write that door's sections, in order

README, repository root -- seven sections

1. **Title and one line** -- what this is, under 120 characters. 2. **What it is and why it exists** -- the problem it solves, who uses it, what it produces. This section explains, so `technical-explanation` governs it: the fixed order (what exists, how it connects, what happens, why) and the plain register are that skill's. 3. **Flow** -- one plain-text flow, and what it interacts with. One, not several. 4. **Requirements** -- tools with their versions, permissions, credentials. 5. **How it is used** -- the real invocation, with the output it is expected to produce. 6. **Structure** -- annotated tree, one line per entry. 7. **License or ownership**.

Requirements sit before usage on purpose: a reader who tries the invocation without them gets a failure they cannot interpret, and a failed first run is what makes them walk away.

README, component folder -- five sections

1. **Narrative** (2-4 paragraphs, prose, no bullets) -- what lives here; why this folder exists separately, which is its conceptual contract; how t