Documentation Skill

---
name: writing-documentation
description: Write or update documentation from the code. Use when the user asks for a README, API reference, guide, docstrings, or says the docs are out of date.
---

# Writing Documentation

Documentation is a claim about behavior. Every claim must be checked against the code before it ships, because a wrong sentence in a document outlives the code it describes and gets believed long after the code changes.

## Read before writing

1. Read the implementation.
2. Read the tests. They document real usage more accurately than any comment, and they are where your examples come from.
3. Read two neighboring documents to learn the conventions: structure, voice, heading style, where docs live.

You do not have the material to write until you have done all three.

## What a document must contain

**Purpose before parameters.** What this does and when to reach for it, before any signature or option list. A reader who cannot tell whether this is the right thing will not read the options.

**A real example.** Take it from a test or an existing call site. If none exists, construct one from the signature and mark it `<!-- untested example -->`. Never invent an example that looks tested. Invented examples are the most common defect in generated documentation and the hardest to catch, because they are syntactically perfect.

**Parameters as the code defines them.** Names, types, defaults, required or optional. Never document an option that does not exist.

**Failure behavior.** The errors actually raised or returned, and what the caller should do about each.

**The non-obvious constraint.** Ordering requirements, side effects, idempotency, limits, concurrency. This is what a reader cannot get from the signature and most needs.

## Rules

- Every statement traces to code you read. Where you cannot determine behavior, write `[VERIFY: the specific question]` rather than a plausible sentence.
- Document what the code does today. Not intent, not the roadmap, not what it should do.
- Do not change source code. If the code contradicts the existing docs, report the contradiction; do not edit either side into agreement.
- Prefer updating an existing document over adding a new one.
- Delete documentation that describes removed behavior. Stale docs are worse than missing ones.

## Before finishing

Reread your document as someone who has never seen this code:
- Could they use it from this alone?
- Is there a sentence you believe but did not verify? Mark it or cut it.
- Does anything only make sense if you already know the answer?

Report: files written, the code read to verify each section, every `[VERIFY]` marker left, and any contradiction found between code and existing docs.