Writing Docs

---
name: writing-docs
description: 'Use when writing or editing a documentation file whose job is to track the repo — README, runbook, CLAUDE.md/AGENTS.md, reference (including the claim-style docs/reference/architecture.md that bootstrapping-docs prescribes), or agent-facing context pack — including converting human or marketing docs into dense agent-facing form, or when tempted to add example output, install steps, or "why" prose. The one door for these repo-tracking docs, across human and agent readers (token bloat, context rot). Out of scope: tutorials, narrative architecture/conceptual overviews and design rationale, and decision records (ADRs) — narrative by design, not line-by-line claims about the repo (growing-docs creates those when demand justifies it). To create a baseline doc set from scratch for an undocumented repo, start with bootstrapping-docs; it routes here for each doc.'
---

# Writing Docs

## Overview

**A doc whose job is to track the repo is a set of claims that must be true of the repo.**
This is the spine: when any guideline conflicts with verifiability, verifiability wins. A
smaller all-true doc beats a complete one with unverifiable parts.

Every assertion unit has one of the document model's four assertion classes:

- **Factual** — commands, paths, symbols, behavior (output included), structure, values.
  Must be mechanically checkable against current evidence.
- **Normative** — instructions and rules. Must name or sit under a current governing source,
  or record the current owner's judgment.
- **Rationale** — the "why", tradeoffs, rejected alternatives. Must be marked and coherent
  with current evidence from a governing decision or implementation source.
- **Non-assertive** — connective prose or signposting. It carries no truth judgment, and is
  the only class that does not.

If an assertion cannot discharge its obligation, cut it or mark it explicitly unverifiable;
classification never makes a living assertion optional.

Scope: as in the frontmatter above — README/runbook/CLAUDE.md/AGENTS.md/reference (incl. claim-style `docs/reference/architecture.md`); not a universal theory of documentation — tutorials/narrative-architecture/ADRs stay narrative (growing-docs), never claim-audited.

## The rules (these address what agents get wrong)

Strong agents already read `package.json` and get commands and flags right. They fail on
the subtler things below. Spend your discipline here.

### 1. Example output is a claim — run it or omit it

Never invent illustrative numbers, sample output, or "looks-right" results. Output you
didn't produce is a fabricated claim, even when it's "just an example."

- Run the command, paste the **real** output.
- If output is environment-dependent (byte sizes, timestamps, hashes), say so instead of
  pinning a fragile exact value.
- Can't run it? Don't show output.

### 2. Normative and rationale assertions need current authority

An instruction is not current merely because it sounds deliberate. Point to the governing
source, or record whose current owner supplied the judgment. If neither exists, do not present
the rule as settled living guidance. Do not weave the "why" into prose as timeless fact.
Put rationale in a marked section and anchor
it to current evidence: `> **Why (current at `bin/cli.js:34`):** reads the whole buffer
because gzip ratio…`. The anchor must let a reviewer judge whether the explanation still
coheres with what exists now; otherwise the rationale is explicitly unverifiable.

### 3. No aspirational claims

Document the repo as it is, not as you assume it will be. No `npm install <pkg>` for an
unpublished package, no "supports X" for unbuilt features. If a claim isn't true yet, omit
it or mark it explicitly as not-yet-true.

### 4. Cut what the reader can already infer

Apply the test: **would removing this line cause the reader to make a mistake?** If not,
cut it. Don't restate what the code, types, or git history plainly show. This bites hardest
in agent docs (see agent-context.md).

### 5. Document-at-all counter-test

Before writing a doc, ask: does the code, a type signature, or git history already say
this? If yes, link to it; don't duplicate it into a doc that will drift. The counter-test
cuts duplication, not demand: a fact derived the hard way twice — by anyone, across sessions
— has falsified "cheaply inferable"; that's a growth signal, see growing-docs.

## Where a doc lives (reader + moment of need)

| Reader, at this moment | Artifact | Guide |
|------------------------|----------|-------|
| Newcomer evaluating / setting up | README | readme.md |
| On-call mid-incident, under pressure | runbook | runbooks.md |
| AI agent starting a session in the repo | CLAUDE.md / AGENTS.md | agent-context.md |
| Agent reading on demand in a multi-unit repo | `docs/reference/` tree (architecture.md, per-unit overview.md) | bootstrapping-docs' repo-shape.md (shape + routing) |
| Reader needing breadth/why — walkthrough, ADR, conceptual overview | durable narrative doc, also under `docs/reference/` (out of this skill's scope) | growing-docs (template + `> As of` anchor) |

## One bar, every reader — then route

The contract above governs **every repo-tracking doc** (see Scope); verifiability never bends.
Audience and job size decide only *how dense* and *who writes it* — never *whether it's true*.
This is the one door for repo-tracking doc writing: don't go looking for a second skill. Two questions, answered once:

**1. Who reads it?**

- **Human** (README, runbook, guide): orient first, skimmable, some warmth OK.
- **Agent** (CLAUDE.md/AGENTS.md, context pack): **density is mandatory, not optional.**
  Maximum signal-per-token, pointers over inline copies, no narrative. The reader can read the
  repo on demand — spend tokens only on what it *can't* reconstruct. This is Rule 4 at full
  strength: an agent doc that "reads fine" but restates inferable facts has **failed**, even if
  every line is true.

**2. Can you verify it without leaving your current context?**

- **Yes — a self-contained edit** (a line or a short section whose claims you can check from what's
  already in front of you) → write it inline, applying the bar.
- **No — you'd have to read code or run commands to verify the claims, or it's more than a few
  lines** → dispatch, so that exploration stays out of your context:
  - **human-facing** → dispatch a general-purpose subagent whose prompt gives the path to
    this SKILL.md and instructs it to read and apply it, plus the same three inputs the
    `llm-doc-writer` branch passes: *what to write from*, *the repo path*, and *the output path*.
  - **agent-facing** → the **`llm-doc-writer` agent** — it owns the densify+verify method and
    runs in its own context. Pass it: *what to write from* (source path, raw content, or topic +
    findings), *the repo path* (puts it in verify mode — anchors every claim to `file:line`,
    runs safe commands), and *the output path*. A one-line agent-doc tweak isn't worth a
    dispatch — apply the density rule inline.

**Do not stop at the first thing that feels sufficient.** If the reader is an agent, the density
pass — inline or via `llm-doc-writer` — is part of *this* job, not a separate skill you may skip.

## Red flags — STOP

- About to type example output you didn't run → run it or delete it.
- Writing "because…" / "the reason is…" in body prose → move to a marked, anchored section.
- `npm install <thing>`, "just run X" you haven't confirmed exists → verify or cut.
- A sentence the reader could get from reading one obvious file → cut it.
- Reader is an agent and you wrote it like a human doc (narrative, restated-inferable facts) →
  the density pass is owed; it is not optional.
- Agent doc that's a whole-doc or needs verification, and you didn't dispatch `llm-doc-writer`
  → you skipped the specialist that enforces density+anchoring in its own context.
- "This skill covers it, I'll just start" on an agent doc → you still owe the density half.

## Reference files

- **readme.md** — README structure, coverage checklist, one verified example, failure modes.
- **runbooks.md** — runbook structure for 3am usability; copy-pasteable steps, real output.
- **agent-context.md** — CLAUDE.md/AGENTS.md; the cut-test, pointers-over-inline, when to
  dispatch the `llm-doc-writer` agent.