Writing Documentation

---
name: writing-documentation
description: Write docs grounded in the actual codebase. Use when asked to write or update a README, setup guide, architecture docs, or onboarding docs.
---

# Writing Documentation

Document what exists, not what should exist. Every command in the docs must be one you verified.

## Grounding pass (mandatory)

1. Read `package.json` / `pyproject.toml` / `go.mod` — real scripts, real entry points, real versions.
2. `rg --files` for config: Dockerfile, compose files, .env.example, CI config. These are your setup instructions.
3. Read the entry point and one layer down to sketch the architecture.
4. List environment variables actually referenced in code: `rg "process.env\.|os.environ"`.

## README structure (in this order)

1. One-paragraph what/why
2. Prerequisites (versions from the real toolchain files)
3. Setup: exact commands, copied from package scripts / compose files, in order
4. Run: dev command, then how to run tests and lint
5. Project layout: a short tree with one line per important directory
6. Environment variables table: name, purpose, required/optional
7. Deployment: only what the CI/config files prove, otherwise omit
8. Troubleshooting: only real failure modes you can point to (port conflicts, missing env, migration steps)

## Rules

- Never invent features, flags, or endpoints. If unsure whether something exists, search for it or omit it.
- Every shell command must be runnable as written — no `<your-key>` placeholders without explaining where to get the value.
- Mark unverifiable assumptions explicitly: "TODO: confirm staging deploy process with team."
- Keep it short. Delete any sentence that does not help someone run or change the project.
- Match the repo's existing tone and heading style if docs already exist.