Writing Docs

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)

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.