/readme-writing

name: readme-writing
description: Use when writing, rewriting, cleaning up, or updating a README -- the root README of a repository, the README of a folder that holds one kind of thing (modules, migrations, components, services, scripts, environments, workloads; Gaia's own agents/, skills/ and hooks/ are one instance of that same shape), or the README shipped inside a template or scaffold handed to someone else. Triggers -- "escribí el README", "actualizá el README", "limpiá el README", "el README de este repo está desactualizado", "falta el README de esta carpeta", "write the README", "the README is stale", or a drift report flagging a README as stale.

README Writing

A README is the mental model someone needs before they touch or adopt the thing it describes. One that only lists files is worse than none: it leaves the reader believing they understand something they do not, and they act on that belief.

Three things hold for every README, whatever it documents, and are stated here once rather than repeated per case:

• **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, so what is in the file is what the reader sees.
• **The concreteness test in Step 3** is the same test for all three cases below.

Step 1: Name the gate

This comes first because it decides everything after it. Three READMEs, three readers, three questions the reader arrives with:

| Gate | Who is reading | The question they arrive with | |------|----------------|-------------------------------| | **Repository root** | Someone evaluating -- they may clone it, adopt it, inherit it, or walk away | "Does this serve me?" | | **Component folder** | Someone about to add, change, or remove something in that folder | "What is this wired to, and what do I break?" | | **Shipped template** | Whoever receives what was generated | "What is mine now, and what do I have to do?" |

The root of a client's Terraform repo, a service, a library, a CLI -- all one gate: repository root. A folder inside a repo that holds one kind of thing -- `migrations/`, `modules/`, `components/`, `services/`, `agents/` -- is the second gate. 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 gate. Naming the gate 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 gate, 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 -- so 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 -- so its README has to keep answering questions long after the first day. A generated client repo whose owners will work in it for a year takes the root gate, generator or not; the template gate is for output whose entire relationship with its reader is the first hour.

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

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. 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.

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 to think about it, as a mental model or analogy; who touches it -- name the actual actors, whichever they are: a developer, a CI job, an operator by hand, a build step, a runtime process, an agent, an end user running a command. 2. **How it is wired in** -- this folder's relation to everything outside it, answering the question its reader actually arrives with: *if I add, change, or remove something here, what happens, and what else has to move?* Two halves, both required -- see below. 3. **What's here** -- annotated tree, one line per file or subdirectory, with generated files marked so nobody hand-edits them. 4. **Conventions** -- how to name new files, what internal structure they must follow, what to update elsewhere when something is added here, what validation runs against this folder. 5. **See also** -- adjacent components, each link carrying its one-line reason.

**Section 2, first half: name the mode this folder lives in, and give the fact that mode demands.**

| Mode | The relation | What the section has to name | |------|--------------|------------------------------| | **Triggered** | something outside fires what is he