/write-docs

name: write-docs
description: >-
  Collaborative authoring workflow for proposals, technical specs, decision docs, READMEs, ADRs, and long-form prose that must work for fresh readers. Three stages: gather context, iterate on structure, reader-test for a stranger. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a doc must be understandable without this session's context.

<objective> Produce documentation that works for a reader landing cold. Not a summary of what was built, not a dump of the conversation, but a document that transfers intent to someone who wasn't here. Run it through three stages — Context → Refine → Reader-Test — and don't ship until a hypothetical reader could act on it. </objective>

<context> GSD already produces durable artifacts (`M###-CONTEXT.md`, `S##-SUMMARY.md`, `DECISIONS.md`, `KNOWLEDGE.md`), but those are scaffolded by templates. This skill is for free-form documentation: README changes, public docs, architectural proposals, RFCs, PR descriptions, runbooks, and anything that lives under `docs/`, `mintlify-docs/`, or `gitbook/` in this repo.

Invocation points:

• User asks to write or rewrite a piece of documentation
• Before shipping a feature that adds user-facing behavior — docs need updates
• After `write-milestone-brief` when the brief needs a public-facing summary for non-GSD consumers
• PR description for a meaningful change

</context>

<core_principle> **WRITE FOR THE FRESH READER.** The test is not "does the maintainer understand it" — you are the maintainer. The test is "can someone who has never seen this code act correctly after reading this?"

**ITERATE STRUCTURE BEFORE PROSE.** An outline that's wrong will not be saved by good sentences. Agree on the sections, what each is for, and in what order before drafting the body.

**NO FILE PATHS IN TRUNK DOCS.** Paths rot. Describe modules, behaviors, and invariants. A README that cites `src/foo.ts:42` is a future broken link. </core_principle>

<process>

Stage 1: Context gathering

1. **Who is the reader?** Internal engineer, open-source contributor, end user, future you at 3am. The answer changes everything. 2. **What should they be able to do after reading?** Name the single post-read action. "Understand the auth flow" is not an action — "implement a new auth provider using the documented extension points" is. 3. **What do they already know?** Assume they have docs for the language and framework, not for your codebase. Don't re-explain React; do explain your project's conventions. 4. **What context from this conversation/codebase belongs in the doc?** Ask the user to dump any missing material. Do not invent examples.

One round of clarifying questions. Then proceed.

Stage 2: Refine structure

1. **Draft an outline, not prose.** Numbered sections, one-line purpose for each. Show it to the user. 2. **Iterate the outline.** Remove sections the reader doesn't need. Reorder so the must-knows come first. Flag sections that can't be written without more input. 3. **Only then, fill sections.** Write the body of each section in order. Keep sentences short. Prefer concrete examples over abstractions. Show small diffs or code snippets where they clarify; skip them where they'd rot. 4. **Draft in place.** Write directly to the target file — `docs/<name>.md`, `README.md`, `mintlify-docs/…`. Do not keep a scratch draft in the conversation.

Stage 3: Reader-test

1. **Cold-read it.** Read the doc top to bottom as if you hadn't written it. Stop at every moment you thought "they already know X" — that's a gap. 2. **Can the named post-read action be taken?** Walk through it. If yes, the doc works. If no, identify the missing piece and add it. 3. **Cut aggressively.** Anything that isn't serving the post-read action comes out. Documentation bloat kills docs. 4. **Offer to the user:** "Here's the draft. Want me to run a fresh sub-agent (`Agent(subagent_type=Explore)`) as a cold reader to stress-test it?"

Stage 4: Wire it in

1. Link to the new doc from relevant entry points (README.md index, docs/ sidebar, mintlify-docs config, etc.). 2. If it documents a decision, also call `gsd_decision_save` with a one-line entry that points at the doc. 3. If it's a public-facing change, flag for the next release notes / CHANGELOG update.

</process>

<anti_patterns>

• **"Writing a summary of what we did"** — the reader doesn't care about the journey. Document the destination.
• **Paths and line numbers in long-lived docs.** They rot. Use module names.
• **Re-explaining general concepts.** If the reader needs to know what HTTP is, the doc is aimed at the wrong audience.
• **Starting with prose.** Outline first, always.
• **Not cold-reading.** Every doc gets one pass as if you've never seen it.
• **Claiming "done" without the reader-test.** Docs that haven't been cold-read are notes, not docs.

</anti_patterns>

<success_criteria>

• [ ] The reader and their post-read action are named explicitly.
• [ ] The outline was agreed before prose was written.
• [ ] A cold-read pass happened; gaps were closed.
• [ ] No file paths or line numbers in the trunk doc (decision-scoped ADRs may include them).
• [ ] Doc is linked from a relevant entry point — it is discoverable, not orphaned.
• [ ] The named action is actually executable after reading.

</success_criteria>