write-feature-docs

write-feature-docs

Draft a complete documentation page for a new Warp feature. You read the feature's spec, verify technical claims by researching the codebase yourself, present a concise outline for the engineer to confirm, then produce a complete MDX draft and open a draft PR in warpdotdev/docs — tagging the docs team for review.

The engineer's job is to confirm what you couldn't verify from the spec and code — not to do a full accuracy review, not to polish prose, not to know docs conventions.

The workflow

1. Find and read the spec files
2. Research the codebase to verify technical claims — minimize what the engineer needs to check
3. Generate a concise outline and wait for engineer confirmation
4. Generate the complete MDX draft 4.5. Attempt screenshot capture via computer use (if available)
5. Open a draft PR in warpdotdev/docs and tag the docs team

---

Step 1: Find and read the spec

Ask the engineer for the spec ID if they haven't provided it. The spec ID is one of:

• A Linear ticket number: APP-1234, REMOTE-1234, QUALITY-408
• A GitHub issue (prefixed with gh-): gh-4567
• A short kebab-case feature name: vertical-tabs-hover-sidecar

Look for the spec files at:

• specs/<id>/PRODUCT.md — primary source: user-facing behavior, what and why
• specs/<id>/TECH.md — secondary source: implementation, data model

Read both files if both exist. PRODUCT.md is the primary driver for the docs content.

When reading TECH.md: (Interactive mode only — in ambient mode, treat all TECH.md-derived content as internal without review; see Ambient mode.) Before incorporating anything from it, identify content that looks like internal implementation detail — database schema, internal service names, private API endpoints, confidential server architecture. Present these flagged items to the engineer and ask them to confirm what's safe to include in public docs and what should stay internal. Do not include anything marked confidential in the draft.

If neither file exists, skip to No-spec fallback.

---

Step 2: Research the codebase

Before presenting the outline, use the GitHub CLI to verify as much technical content as possible yourself — reducing what the engineer needs to confirm to only what you genuinely cannot determine from the code.

Things to verify from code:

• Feature flag name: search for a safe feature token from the spec title or ticket. Before any shell use, reduce it to an allowlisted token matching ^[A-Za-z0-9][A-Za-z0-9_-]*$ and skip the shell search if you cannot produce one safely; then run FEATURE_TOKEN="<validated-token>" && gh search code "${FEATURE_TOKEN}" --repo warpdotdev/warp-internal.
• UI strings: search for user-visible button labels, menu item names, or setting names referenced in the spec
• Settings paths: confirm exact Settings menu paths (e.g., **Settings** > **AI** > **Knowledge**)
• CLI commands or keyboard shortcuts mentioned in the spec
• Related features: identify other features that cross-reference this one for "Related pages"
• Engineer to tag: identify the GitHub handle of the engineer who owns the spec.
  • Interactive mode: run gh api user --jq .login to get the handle of the person currently running the skill — use this only when the skill is being invoked directly by the spec engineer. If a docs team member or non-author is running the skill, use the discovery steps below instead.
  • Ambient mode and non-author interactive runs: before running any lookup commands, validate that the spec ID contains only alphanumeric characters and hyphens (matching ^[A-Za-z0-9][A-Za-z0-9-]*$). If the spec ID contains any other characters, skip the lookup entirely and use [TODO: tag spec author] as a placeholder. If the spec ID is valid, assign it to SPEC_ID and work through these steps in order, stopping as soon as a handle is found:
    1. Check Co-authored-by: trailers in the commit message — in repos that mirror from a private source (like warp-internal), the sync bot is the commit author but the real author appears in a Co-authored-by: trailer. Extract the first non-bot entry:

       git log --follow -1 --format="%B" -- "specs/${SPEC_ID}/PRODUCT.md" \
         | grep -i "^Co-authored-by:" \
         | grep -v "\[bot\]" \
         | head -1 \
         | grep -oP '<[^>]+>' | tr -d '<>'
       

       This returns an email (possibly a GitHub noreply address). If the email matches the pattern <userid>+<username>@users.noreply.github.com, extract the handle directly: echo "$EMAIL" | grep -oP '\+\K[^@]+'. If it's a real email, resolve it via gh api "search/users?q=${EMAIL}+in:email" --jq '.items[0].login'.
    2. Parse the synced-from PR URL — some sync bots embed the original PR URL in the commit body (e.g. Synced from warp: https://github.com/warpdotdev/warp/pull/11901). Extract it and fetch the PR author:

       ORIG_PR=$(git log --follow -1 --format="%B" -- "specs/${SPEC_ID}/PRODUCT.md" \
         | grep -oP 'https://github\.com/[^/]+/[^/]+/pull/\d+' | head -1)
       # Extract owner/repo and PR number, then: gh pr view <N> --repo <owner/repo> --json author --jq '.author.login'
       

    3. Search the origin repo PRs — try the repo that actually owns the code (checking both the public mirror and the private source if accessible):

       gh pr list --search "specs/${SPEC_ID}" --repo warpdotdev/warp-internal --state merged --json author --limit 1 --jq '.[0].author.login'
       # Also try: gh pr list --search "specs/${SPEC_ID}" --repo warpdotdev/warp --state merged --json author --limit 1 --jq '.[0].author.login'
       

       Skip any result where the login contains [bot].
    4. Fall back to commit author email — only if the email does NOT contain [bot]:

       EMAIL=$(git log --follow -1 --pretty=format:"%ae" -- "specs/${SPEC_ID}/PRODUCT.md")
       

       If ${EMAIL} is non-empty and bot-free, resolve it to a handle via gh api "search/users?q=${EMAIL}+in:email" --jq '.items[0].login'.
    5. If no handle is found after all steps, use [TODO: tag spec author] as a placeholder in the PR body.

For each claim you verify from code, mark it confirmed. For claims you can't verify (UI behavior not in code, product intent, behavior of unreleased features), flag them as [UNVERIFIED] in the outline — those are the only things the engineer needs to focus on.

---

Step 3: Generate and present the outline

Generate a concise outline — no prose. The outline shows what you've confirmed from research and exactly what still needs engineer input.

Print the outline to the terminal in this format:

📄 Docs outline for [Feature name]

PROPOSED PLACEMENT
  Section:  src/content/docs/<section>/   (e.g., agent-platform/cloud-agents/)
  File:     <feature-name>.mdx
  URL:      docs.warp.dev/<path>/<feature-name>

CONTENT SECTIONS
  H1:  <Feature name>
  Opening paragraph: [1-sentence description of what you'll write]
  ## Key features — [which 2-4 capabilities to highlight as bullets]
  ## How it works — [the conceptual model: what and why, no steps]
  ## <Usage section title> — [e.g., "Creating environments", "Configuring X"]
      Prerequisites: [any prerequisites to list]
      Steps:
        1. [Step description]
        2. [Step description]
        3. [Step description]
        ...
  ## Related pages — [cross-links to suggest]

The sections above are defaults. Adapt the outline to the feature: omit ## How it works if the feature needs no conceptual explanation, add multiple usage sections if the feature has distinct workflows, and collapse ## Key features into the opening paragraph if the feature is simple enough.

VERIFIED FROM CODEBASE ✅
  - [e.g., "Feature flag: `my_feature_flag` confirmed in warp-internal"]
  - [e.g., "Settings path: confirmed as Settings > AI > Agents > Permissions"]

NEEDS YOUR CONFIRMATION ⚠️
  - [e.g., "Step 3 — does the sync trigger automatically or require a manual action?"]
  - [e.g., "Is the 'Export' button visible before the feature flag is enabled?"]

After printing the outline, say:

"I've verified what I could from the codebase. Please check the items marked ⚠️ above and reply with any corrections, or say 'looks good' to proceed."

Wait for the engineer's reply before continuing. Incorporate their feedback, then draft.

---

Step 4: Generate the MDX draft

Generate a complete .mdx file based on the confirmed outline. The output is ready to drop directly into warpdotdev/docs.

Template structure

---
description: >-
  [1-2 sentence standalone summary. Lead with the user benefit. Include the
  feature name and a key term or two so it works as a search result snippet.]
---

# [Feature name]

[Opening paragraph: what the feature does and its primary benefit.
1-3 sentences. Lead with what the user can accomplish, not the implementation.]

:::note
[Optional: key context the reader needs upfront — a prerequisite, a limitation,
or when NOT to use this feature. Delete this callout if nothing applies.]
:::

## Key features

* **Feature A** - What it does and why it matters to the user.
* **Feature B** - What it does and why it matters to the user.

## How it works

[CONCEPTUAL section: explain system behavior, data flow, or architecture.
Answer "what" and "why" before "how." Define any new terms when they
first appear. Do NOT include step-by-step procedures in this section —
keep conceptual and procedural content clearly separated.]

## [Usage section title]

[PROCEDURAL section: motivate the task first, then give numbered steps.
Briefly explain why the user is doing this before telling them how.]

### Prerequisites

* **[Prerequisite]** - What it is and where to get it. See [full reference](link-here).

### [Task name — sentence case, e.g., "Create an environment with the CLI"]

1. First step. Expected outcome if not obvious.
2. Second step.
3. Third step.

## Related pages

* [Related feature](../path/to/page.md)
* [Deeper guide](../path/to/guide.md)

Style rules — apply exactly

These conventions come from the Warp docs style guide and must be followed:

Headings

• Sentence case for all headings: capitalize only the first word and proper feature names
• Proper feature names keep their capitalization: "Agent Mode", "Warp Drive", "Oz", "Command Palette"
• ✅ ## How it works — ❌ ## How It Works
• ✅ ## Agent Mode settings — ❌ ## Agent mode settings

Lists

• Bold term + dash + description: * **Term** - Description
• Never use a colon: ❌ * **Term**: Description

UI elements and paths

• Bold for buttons, links, menu items: Click **Save**, not Click `Save`
• Bold each segment in a Settings path, leave > plain: **Settings** > **AI** > **Knowledge**

Voice and tone

• Second person: "you can," "allows you to"
• Active voice: "Warp indexes your codebase" — not "your codebase is indexed"
• Avoid "simple," "easy," "just" — these dismiss the reader's experience
• Present tense for how things work; imperative for instructions

Frontmatter description

• Write as a standalone summary that works as a search result snippet
• Lead with user benefit, include the feature name and key terms
• ✅ Environments ensure your cloud agents run with a consistent toolchain. Learn when to use environments and how to configure them.
• ❌ This page describes environments.

Callout syntax (Astro Starlight)

• :::note — supplemental context, tips
• :::caution — caveats, limitations
• :::danger — destructive or irreversible actions
• :::tip — helpful hints and best practices

What to leave as [TODO: docs reviewer — ...] placeholders

• Screenshots where computer use fails the quality gate, is unavailable, or the feature isn't yet shipped
• Video/GIF embeds
• Exact Settings path if the feature hasn't shipped yet
• Final URL path (docs team confirms placement)
• Any behavior that remained unverified after engineer confirmation

---

Step 4.5: Capture screenshots via computer use (if available)

After generating the draft, attempt to capture screenshots for any [TODO: docs reviewer — screenshot needed] placeholders using computer use. This step is optional — only run it if the computer_use tool is available. If computer use is unavailable, leave all placeholders as-is.

Decide which screenshots to attempt

Only attempt screenshots where all of the following are true:

• The feature is already shipped (not behind a feature flag or unreleased)
• The UI state can be reliably navigated to programmatically
• The placeholder specifies a concrete UI surface (not vague like "show the feature working")

Skip screenshots that require account-specific state, specific data, or content that would expose sensitive information.

Pre-capture setup

Before taking any screenshot:

1. Launch Warp at a consistent window size (use the warp-internal-computer-use skill for launch guidance)
2. Navigate to the relevant UI surface or trigger the relevant feature state
3. Wait for all animations to complete and the UI to be fully settled
4. Dismiss any unrelated popups, notifications, or toasts that aren't part of the feature being documented
5. Close any sidebar panels or panes not relevant to this screenshot
6. Verify no sensitive data is visible: check for tokens, API keys, private repo names, customer workspace data, email addresses, or personal information. If any is visible, do not take the screenshot.

Capture protocol: predict → capture → verify → retry once

This is a structured self-verification loop. Do not skip it — it's the primary guard against wrong-state, wrong-crop, and wrong-framing captures.

Step 1: State the expectation before capturing

Before taking any screenshot, write out what you expect to see:

CAPTURE EXPECTATION
  Subject:            [The specific UI element or surface being documented]
  Expected elements:  [2-3 specific things that MUST be visible — e.g. a panel title, a button, a specific setting]
  Expected state:     [The UI state — e.g. "Settings panel open", "Modal visible", "Feature active and showing output"]
  Must not contain:   [Anything that must NOT be visible — e.g. sensitive data, unrelated popups, loading spinners]

Step 2: Capture

Take the screenshot.

Step 3: View and verify against the expectation

Use computer use to view the captured image, then check it against the expectation:

• Is the stated subject visible and clearly the focal point?
• Are all expected elements present?
• Is the UI in the expected state (not a transitional or loading state)?
• Is anything from must not contain visible?
• Is text legible at the target display width?

If all pass → proceed to the quality gate.

If any fail → attempt once more: re-navigate to the UI state, wait l

...