write-the-docs

Write the docs

Drafts net-new (or substantially rewritten) Supabase docs content for a feature or launch. Distinct from work-linear-issue, which implements and fixes existing docs tickets — this skill is for the case where the content doesn't exist yet and has to be authored from scratch, 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 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 CONTRIBUTING.md and WORD_LIST.md; say so when you fall back to a precedent page. Don't silently invent voice/structure rules — name the nearest existing-page precedent you followed instead (see reference/style-fallback.md).
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.

Phase 1 — Gather (read-only)

Four inputs, in order:

1. Style guide. Start with apps/docs/CONTRIBUTING.md and apps/docs/WORD_LIST.md for voice, structure, and terminology. If those don't cover the case, fall back to the nearest comparable existing page under apps/docs/content/ and say explicitly: "no dedicated style guide yet — following the precedent of <page>." See reference/style-fallback.md.
2. Linear — the ticket and its product context. Pull the Linear issue itself, then don't stop there: pull 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, not in the ticket body — see how the Select 2026 initiative's own description carried the real launch narrative, not any single project's ticket. Distinguish scope the ticket actually commits to from aspirational language in the PRD.
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. 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.

Phase 2 — Draft

• Follow apps/docs MDX conventions (component usage, frontmatter, code sample wiring) — see ask-the-docs for the pipeline details rather than re-deriving them.
• Place the page using existing IA precedent; for a placement call that isn't obvious, consult audit-docs-ia's nav/IA knowledge rather than guessing a nav slot.
• Wire it into navigation, not just onto disk. Placement (which section) and nav enablement (whether it actually shows up) are separate — confirm the current nav-registration mechanism via ask-the-docs/audit-docs-ia rather than assuming a page is discoverable just because the file exists in the right folder.
• Ground every behavior claim in Phase 1's code read (the linked PR when there is one); ground every "why this matters" framing in the PRD/PM context; mark inferred material inline (e.g. an HTML comment or a flagged line in the handoff summary) so a reviewer can find it fast.

Phase 2.5 — Review checklist

Before handing off, confirm:

• CONTRIBUTING.md / WORD_LIST.md followed, or precedent page named explicitly
• Every behavior claim traces to the code read (ideally the linked PR), not just the PRD
• Every "why it matters" / positioning line traces to Linear/PM context, not invented
• Inferred or assumed material is flagged, not stated as fact
• Content type confirmed as Guide/Troubleshooting (not something that belongs in generated Reference instead)
• Nav placement and nav enablement both wired, not just the placement
• Internal links resolve; first-use of new terms/acronyms is defined

Phase 3 — Handoff

This skill stops at a reviewable draft. It does not open worktrees or PRs itself:

• Hand off to create-pull-request (and work-linear-issue if the ticket needs a full worktree+PR flow) for the actual PR mechanics. Carry the Phase 1/2 flagged-assumptions list forward explicitly into that handoff — it belongs in the PR description (e.g. a "needs review" section) so a reviewer sees it, not just as an inline comment buried in the draft.
• If the feature is UI-driven and the PR will need screenshots/GIFs, flag proof-it-works as the next step rather than capturing evidence here.

Additional resources

• Style / terminology: apps/docs/CONTRIBUTING.md, apps/docs/WORD_LIST.md, reference/style-fallback.md
• Content-type gate detail: reference/content-type-gate.md
• "Write the docs" checklist (Draft stage): pm-the-docs's reference/write-the-docs-checklist.md
• Docs-app architecture/placement: ask-the-docs, audit-docs-ia
• PR mechanics: create-pull-request, work-linear-issue
• Screenshots/proof: proof-it-works