Documentation

Write the shortest complete path that lets the intended reader achieve a real outcome and verify it. Treat implementation, public APIs, configuration, tests, CI, and established project terminology as the source of truth.

Choose the document shape

Split conflicting modes into linked pages instead of making one page serve all four.

Core workflow

1. Identify the reader, desired outcome, document shape, and success check.
2. Inspect the implementation, public contract, configuration, scripts, tests, CI, existing terminology, and related docs before writing.
3. Verify every command, flag, path, version, output, and behavior claimed.
4. Write prerequisites before actions and place validation immediately after the action it verifies. Include recovery where failure is plausible.
5. Use typed, copy-pasteable examples with realistic placeholders. Do not invent APIs or filenames; prefix expected shell output with # when it shares a command block.
6. Validate links, anchors, examples, commands, generated references, rendering, and repository documentation checks where available.

Label unverifiable assumptions or omit them. Never present stale or uncertain instructions as authoritative.

Reference router

Open only the reference whose trigger matches the task:

• README guidance — project entry points, quickstarts, success checks, and the learning ladder.
• API documentation — public contracts, errors, side effects, limits, and generated references.
• GitHub Markdown — headings, links, alerts, collapsed sections, tables, diagrams, badges, and accessible rendering.
• Documentation testing — executable examples, vocabulary guards, fixtures, and docs CI.

Completion gate

Confirm that the reader can complete the task in one pass; claims and examples match source truth; prerequisites, permissions, side effects, and recovery are explicit; links and rendering validate; and no filler, marketing claims, hidden steps, or unsupported certainty remain.

Output

Report files and sections changed, reader/outcome/document shape, source-of-truth files consulted, validation commands and results, and any remaining assumptions or documentation gaps.