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, confirm the content design plan and then the outline with the engineer, and only 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. Present the content design plan and wait for confirmation — who the page is for
4. Present the outline and wait for confirmation — what the page will contain
5. Generate the complete MDX draft

5.5. Attempt screenshot capture via computer use (if available)

1. Open a draft PR in warpdotdev/docs and tag the docs team

Steps 3 and 4 are two separate confirmations, in that order. The outline is derived from the plan — the plan picks the content type, and the content type determines what sections the outline has. Presenting them together would show the engineer an outline built on an audience they have not agreed to yet, and they would anchor on the concrete outline instead of reconsidering the question above it. Settle who the page is for, then decide what goes in it.

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`: 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.

This confirmation is why the skill requires a present engineer. There is no unattended path: without someone to say what is safe to publish, TECH.md content cannot be drafted at all.

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

Step 2: Research the codebase

Before presenting the plan or 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.
• Non-author runs (a docs team member or anyone who did not write the spec): 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: ``bash 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: ``bash 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): ``bash 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]: ``bash 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: Present the content design plan and wait

This is the first of two confirmations, and it comes before the outline. Settle who the page is for before deciding what goes in it.

Fill in .agents/templates/content-design-plan.md from the docs repo, using .agents/references/content-design-plan.md for what each field is asking: audience and JTBD, problem, goals, purpose and value, content type, skill and template, and high-impact scenarios with explicit exclusions.

Print it to the terminal, then say:

"Before I outline the page, please confirm this is the right reader and the right job. Correct anything that's off, or say 'looks good' and I'll draft the outline."