Write The Docs

Write the docs

Drafts net-new Supabase docs content (or product-grounded rewrites) for a feature or launch. Distinct from work-linear-issue, which implements and fixes existing docs tickets, and from edit-the-docs, which restructures and tightens pages that already exist without gathering net-new product intent. This skill is for the case where the content doesn't exist yet (or must be rewritten from intent + code), grounded in four inputs rather than guessed.

Core rules

1. Gather before drafting. Never draft from a ticket title alone. Pull all four inputs below first; a thin gather phase produces a draft that's wrong about how the feature actually works.
2. Separate confirmed behavior from product intent from inference. Code tells you what the feature does today. Linear/PRD/PRFAQ (or prior Frame/Shape output) tells you what it's meant to do and how it should be positioned. Anything you had to guess, flag explicitly rather than stating it as fact.
3. Follow the style guide for writing conventions, including voice, terminology, formatting, page structure, and elements. Never follow it for content accuracy. It is a style reference, not a source of truth: rule 2's Linear+code read is what governs what the page actually says. Don't invent voice or structure rules. When the guide and Google's developer documentation style guide both come up short, say so in the handoff rather than copying whatever the nearest page happens to do.
4. Reuse, don't duplicate. For docs-app architecture/placement questions, use ask-the-docs and audit-docs-ia rather than re-deriving that knowledge here.
5. Know what you're actually drafting. Not everything that looks like "docs for a feature" is a hand-written page — see the content-type gate below before you start writing. If the ask is restructure, reorder, connective text, or clarity on an existing page (no new product story), use edit-the-docs instead.

Phase 1 — Gather (read-only)

Four inputs, read in this sequence (sequence, not priority; Linear remains the product-intent source and code remains the behavior source per rule 2 and Phase 1 step 3):

1. Style guide — voice/terminology reference. Read style-guide/README.md and follow the step that matches what you're drafting. Check WORD_LIST.md for the terms you plan to introduce. The guide's closing section says what to consult when it's silent; follow that rather than matching a neighbouring page.
2. Linear — the ticket and its product context. Linear is an internal Supabase tool: preferred when available, not required for open-source contributors. When a Linear issue is available, pull it, then its parent project/initiative description too (PRD, PRFAQ, RFC, or initiative narrative) and any PM comments. Product framing/positioning language usually lives one level up from the ticket, in the parent project or initiative description rather than the ticket body. Distinguish scope the ticket actually commits to from aspirational language in the PRD. If there is no Linear issue and no prior Frame/Shape product-intent output, stop drafting: ask internal authors for a Linear URL, otherwise hand off to pm-the-docs (Frame) and ask-the-docs when Shape/IA is unsettled. Resume only after product intent exists — never invent positioning, and never run Frame/Shape inside this Draft skill.
3. Code. Read the actual implementation before writing a single behavior claim — the PRD describes intent, the code describes what shipped. Check the Linear issue/project first for a linked supabase/supabase PR — its diff and description are the most precise "what actually shipped" source, more precise than a general codebase read. If no PR is linked, locate the feature directly in supabase/supabase (or the product's own repo), and apply ask-the-docs's reuse/minimalism lens: understand what exists before describing it. When behavior spans services (CLI, Auth, migrations, platform, …), follow pm-the-docs → universe-lookup capability gate (universe when accessible, else OSS public search / linked repos — not ask-the-docs). If code and PRD disagree, the code wins for behavior claims — flag the mismatch rather than silently picking one.
4. Whatever else the author supplies. Screenshots, example projects, related pages, Slack threads, a specific voice sample. Screenshots are for more than general context — use them to verify the exact button/menu/field labels before writing instructional steps that reference them; a mismatched UI label is one of the easiest, most avoidable errors in a draft. Ask for these when the feature's user-facing shape is still unclear after 1–3, rather than guessing.

Summarize all four back to the requester before drafting: what's confirmed, what's product intent vs. shipped behavior, what's still a gap. Stop and ask if a real gap would change the draft's structure or scope.

Phase 1.5 — Content-type gate

Before drafting, classify what's actually being asked for against apps/docs's real content types (see ask-the-docs's app-map.md "Content types" table, and reference/content-type-gate.md here):

• Guide / tutorial — hand-written MDX under content/guides/. This is what this skill drafts.
• Troubleshooting — hand-written MDX under content/troubleshooting/, sometimes synced from GitHub issues. Also in scope.
• Reference — generated from spec/ (OpenAPI, SDK YAML, CLI config) → features/docs/generated/**. Not hand-authored via the standard MDX path. If the ask is actually reference-type content (a new API endpoint, config option, or SDK method that needs a reference entry), stop drafting MDX — it would diverge from or get silently overwritten by the generator. Instead point to the spec/codegen pipeline (apps/docs/spec/, apps/docs/generator/; see ask-the-docs's management-api-reference.md for the OpenAPI-specific flow) and say so explicitly rather than producing a page that looks done but isn't the real fix.

When in doubt, ask ask-the-docs rather than guessing — this classification is the one call in this skill most likely to be wrong if made from outside knowledge of the app.