docs · diff

git:20260917.86a6fe7 to git:20260926.79fd139

18 added, 12 removed. Audit A to A.

---

name: docs

description: "Documentation for people, through tech-writer — README from technical-preferences and the product spec, API reference generated from the contract (GraphQL SDL / OpenAPI), user guide from the feature specs, runbook from docs/ops/deploy.md and the incident history; every command in the docs is run before it is written; --check only reports what is missing or stale. Use when documentation is missing or stale, before a hand-over and before a release."

argument-hint: "[readme | api | guide | runbook | all] [--check]"

user-invocable: true

allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion

model: sonnet

---

# Docs — documentation for people

Reply in the project conversation language (CLAUDE.md → Language); code, identifiers, paths and commit messages stay in English.

Agent `tech-writer` (rules: README structure, runbook structure, every command run, no duplication of CLAUDE.md

or the stack reference). Sources: `technical-preferences.md`, `docs/specs/product-spec.md`, `docs/specs/features/*.md`,

the API contract (`docs/architecture/api/api-contract.md` and the schema file at `api_contract_path` (technical-preferences; default `api/schema.graphqls` for a Go module, `docs/architecture/api/schema.graphql` otherwise)), `docs/ops/deploy.md` (template `deploy-runbook.md`), `docs/ops/incidents/*`, `CHANGELOG.md`.

Writes only after "May I write?". Documentation is derived from the pipeline's documents, never the other way round —

a fact missing from a spec or the contract is a spec gap (`/feature-spec`, `/api-contract`), not something to invent here.

## Phase 1: Inventory (`--check` stops after it)

- Per target: what exists (`README.md`, `docs/api/*`, `docs/guide/*`, `docs/ops/*.md`), its last change vs the

- last change of its sources (`git log -1 --format=%cs -- <path>`), and the gaps: README without a quick start, an

- env table that misses variables present in `.env.example` or compose, an API reference behind the contract

- (`graphql-inspector diff` / `openapi-diff` when installed, otherwise operation lists compared), a user guide

- that does not cover a Done feature, a runbook without rollback or without the last incident's action. Table

- "target → exists → stale vs → gaps". `--check` → verdict `COMPLETE (check only: N targets stale)` and stop.

+ 1. **Per target, what exists**: `README.md`, `docs/api/*`, `docs/guide/*`, `docs/ops/*.md`.

+ 2. **Staleness**: its last change vs the last change of its sources (`git log -1 --format=%cs -- <path>`).

+ 3. **Gaps**:

+ - a README without a quick start, or an env table that misses variables present in `.env.example` or compose;

+ - an API reference behind the contract (`graphql-inspector diff` / `openapi-diff` when installed, otherwise operation lists compared);

+ - a user guide that does not cover a Done feature;

+ - a runbook without rollback or without the last incident's action.

+ 4. **Missing sources**: a target whose source does not exist (`api` with no contract; `readme` with no product spec) → `BLOCKED (no product spec / no contract — run /product-spec | /api-contract first)`, naming only the missing one. No hand-written substitute is drafted.

+ 5. **Table** "target → exists → stale vs → gaps". `--check` → verdict `COMPLETE (check only: N targets stale)` and stop.

## Phase 2: Draft (tech-writer via Task, one target at a time)

+ The brief asks `tech-writer` for the draft and the output of every command it ran, not for a write: the write gate is this session's (Phase 3). Questions the agent has come back in its result, and this session asks them.

- **readme** — what it is (product spec §1) → quick start (commands from technical-preferences and the test

strategy, **run here with output**) → configuration (env table from `.env.example`/compose, secrets named, never

valued) → development (tests, lint, `/help`) → deploy (link to the runbook) → licence. Never duplicates CLAUDE.md.

- **api** — generated from the contract: GraphQL SDL → reference per type/operation with descriptions taken from

the SDL (`graphql-markdown` or an equivalent from `stack-reference/graphql.md`; a hand-written page only when no

generator fits, and then marked so); OpenAPI → Redoc/Scalar page or markdown per operation. Auth, errors, limits

and deprecations come from the contract, not from memory.

- **guide** — one page per Done feature, from the feature spec's scenarios and UI states: the user's goal, steps,

what they see in each state, what can go wrong (edge cases with the concrete behaviour the spec names);

screenshots only when a Playwright run can take them.

- **runbook** — `docs/ops/deploy.md` completed from the deploy contract, the release files and the incidents:

symptom → diagnosis (commands) → action → verification → rollback, per known failure; secrets by name and

location only.

- Each draft is rendered in the chat (rule 7); a command that fails when run is a finding, not prose.

- ## Phase 3: Write

- Per target: "May I write `<path>`?" — one `AskUserQuestion`: write (Recommended) · adjust · skip. After the "write"

- answer: `touch .claude/.write-consent` (rule 7 — the consent-guard hook checks the marker). Then one commit gate:

- `docs: <target> from <sources>` staging exactly the written files, on the branch git-workflow's documents lane

- prescribes (a story branch when the docs belong to the story in progress).

+ Each draft is rendered in the chat (rule 7). A command that fails when run is a finding, not prose.

+ ## Phase 3: Write (per target)

+ 1. "May I write `<path>`?" — one `AskUserQuestion`: write (Recommended) · adjust · skip.

+ 2. After the "write" answer: `touch .claude/.write-consent` (rule 7 — the consent-guard hook checks the marker). Then write.

+ 3. **Commit gate**, one `AskUserQuestion`: `docs: <target> from <sources>`, staging exactly the written files, on the

+ branch the documents lane of `git-workflow.md` prescribes (a story branch when the docs belong to the story in

+ progress; name the branch in the question).

Verdict: `COMPLETE (N targets written)` | `COMPLETE (check only: …)` | `BLOCKED (no product spec / no contract —

run /product-spec | /api-contract first)`. Next step — one `AskUserQuestion`: `/story-done S-NNN` when the docs

close a story (Recommended in that case) · `/release-checklist` before a release · stop here.