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)

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)

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 (rule 7, .claude/docs/git-workflow.md § Documents), right after the write, one AskUserQuestion: docs: <target> from <sources>, staging exactly the written files.
   • On the default branch when no story work is in progress.
   • When HEAD is a story branch, name it and ask: commit here (Recommended when the docs belong to the story in progress — a runbook or guide for the feature that branch implements) · switch to the default branch and commit there (Recommended when the target is pipeline-wide, e.g. a README refresh) · leave uncommitted. Exactly one option is marked Recommended, by the target's provenance.
   • Before asking, record the gate — <hooks>session-state.sh set Gate "/docs Phase 3: commit <target>?" (<hooks> is .claude/hooks/ in copy mode and ${CLAUDE_PLUGIN_ROOT}/hooks/ in plugin mode) — and clear it after the answer (<hooks>session-state.sh set Gate "—").
   • Nothing is committed without the answer; a target the user skipped at step 1 is not staged.

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.