Back to Details

write-feature-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
为Warp新功能起草完整的文档页面。你会阅读功能规范，通过研究代码库验证技术说明，向工程师呈现简洁的大纲供确认，然后生成完整的MDX草稿，并在
warpdotdev/docs
仓库中打开草稿PR——标记文档团队进行审核。
工程师的工作是确认你无法从规范和代码中验证的内容——无需进行全面的准确性审查、润色文案，也无需了解文档规范。

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, distinguishing verified facts from open questions
  4. Engineer confirms or corrects
  5. Generate the complete MDX draft
  6. Attempt screenshot capture via computer use (if available)
  7. Open a draft PR in 
    warpdotdev/docs
    and tag the docs team
  1. 查找并阅读规范文件
  2. 研究代码库以验证技术说明——尽量减少工程师需要核对的内容
  3. 生成简洁的大纲，区分已验证事实和待确认问题
  4. 工程师确认或修正
  5. 生成完整的MDX草稿
  6. 通过计算机操作捕获截图（若可用）
  7. 在
    warpdotdev/docs
    中打开草稿PR并标记文档团队

Step 1: Find and read the spec

步骤1：查找并阅读规范

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
  • 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.
If neither file exists, skip to No-spec fallback.
如果工程师未提供规范ID，请向其索要。规范ID可以是以下类型之一：
  • Linear工单编号：
    APP-1234
  • GitHub议题（前缀为
    gh-
    ）：
    gh-4567
  • 短横线命名的功能名称：
    vertical-tabs-hover-sidecar
在以下位置查找规范文件：
  • specs/<id>/PRODUCT.md
    — 主要来源：面向用户的行为、功能内容及设计初衷
  • specs/<id>/TECH.md
    — 次要来源：实现方式、数据模型
若两个文件都存在，请均阅读。
PRODUCT.md
是文档内容的主要依据。
阅读
TECH.md
时：在纳入其中的任何内容之前，先识别出看起来属于内部实现细节的内容——数据库schema、内部服务名称、私有API端点、保密的服务器架构。将这些标记的内容提交给工程师，询问他们哪些内容可以安全地包含在公开文档中，哪些应保留为内部内容。请勿在草稿中包含任何标记为保密的内容。
若两个文件都不存在，请跳至【无规范 fallback](#no-spec-fallback)】。

Step 2: Research the codebase

步骤2：研究代码库

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: 
    gh search code "<feature-name>" --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"
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.
在呈现大纲之前，使用GitHub CLI尽可能多地自行验证技术内容——将工程师需要确认的内容减少到你确实无法从代码中确定的部分。
需要从代码中验证的内容：
  • 功能标志名称：
    gh search code "<feature-name>" --repo warpdotdev/warp-internal
  • UI字符串：搜索规范中提到的用户可见按钮标签、菜单项名称或设置名称
  • 设置路径：确认准确的设置菜单路径（例如：
    **Settings** > **AI** > **Knowledge**
    ）
  • CLI命令或键盘快捷键：规范中提到的相关内容
  • 相关功能：识别与该功能关联的其他功能，用于「相关页面」部分
对于从代码中验证的每一项内容，标记为已确认。对于无法验证的内容（代码中未体现的UI行为、产品意图、未发布功能的行为），在大纲中标记为
[UNVERIFIED]
——这些是工程师唯一需要关注的内容。

Step 3: Generate and present the outline

步骤3：生成并呈现大纲

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]

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.
生成简洁的大纲——无需文案。大纲需展示你从研究中确认的内容，以及仍需工程师输入的具体内容。
按以下格式在终端中打印大纲：
📄 [功能名称]的文档大纲

建议放置位置
  章节:  src/content/docs/<section>/   (例如: agent-platform/cloud-agents/)
  文件:     <feature-name>.mdx
  URL:      docs.warp.dev/<path>/<feature-name>

内容章节
  一级标题:  <功能名称>
  开篇段落: [你将撰写的一句话描述]
  ## 核心功能 — [需突出的2-4项功能，以项目符号展示]
  ## 工作原理 — [概念模型：内容及设计初衷，无需步骤]
  ## <使用章节标题> — [例如：“创建环境”、“配置X”]
      前置条件: [需列出的所有前置条件]
      步骤:
        1. [步骤描述]
        2. [步骤描述]
        3. [步骤描述]
        ...
  ## 相关页面 — [建议的交叉链接]

已从代码库验证 ✅
  - [例如：“功能标志：`my_feature_flag`已在warp-internal中确认”]
  - [例如：“设置路径：已确认为Settings > AI > Agents > Permissions”]

需你确认 ⚠️
  - [例如：“步骤3——同步是自动触发还是需要手动操作？”]
  - [例如：“‘导出’按钮在功能标志启用前是否可见？”]
打印大纲后，告知工程师：
"我已从代码库中验证了尽可能多的内容。请检查上面标记为⚠️的项目，并回复任何修正，或回复‘看起来没问题’以继续。"
等待工程师回复后再继续。整合他们的反馈，然后开始起草。

Step 4: Generate the MDX draft

步骤4：生成MDX草稿

Generate a complete 
.mdx
file based on the confirmed outline. The output is ready to drop directly into 
warpdotdev/docs
.
根据确认后的大纲生成完整的
.mdx
文件。输出内容可直接放入
warpdotdev/docs
仓库。

Template structure

模板结构

mdx
---
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.]
---
mdx
---
description: >-
  [1-2句话的独立摘要。以用户收益开头，包含功能名称和一两个关键词，使其适合作为搜索结果片段。]
---

[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.] :::
[开篇段落：功能作用及其主要收益。1-3句话。以用户可实现的目标开头，而非实现细节。]
:::note [可选：读者需要提前了解的关键背景——前置条件、限制条件或不适用场景。若无相关内容，请删除此提示框。] :::

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.
  • 功能A - 作用及对用户的重要性。
  • 功能B - 作用及对用户的重要性。

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.
  • [前置条件] - 内容及获取途径。请查看完整参考文档。

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

[任务名称——句首大写，例如：“使用CLI创建环境”]

  1. First step. Expected outcome if not obvious.
  2. Second step.
  3. Third step.
  1. 第一步。若预期结果不明确，请说明。
  2. 第二步。
  3. 第三步。

Related pages

相关页面

  • Related feature
  • Deeper guide
undefined
  • 相关功能
  • 深度指南
undefined

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
    — confirmation of expected outcomes
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
这些规范来自Warp文档样式指南，必须严格遵守：
标题
  • 所有标题采用句首大写格式：仅首单词和专有功能名称大写
  • 专有功能名称保留原有大小写："Agent Mode"、"Warp Drive"、"Oz"、"Command Palette"
  • ✅ 
    ## How it works
    — ❌ 
    ## How It Works
  • ✅ 
    ## Agent Mode settings
    — ❌ 
    ## Agent mode settings
列表
  • 加粗术语 + 破折号 + 描述：
    * **Term** - Description
  • 请勿使用冒号：❌ 
    * **Term**: Description
UI元素及路径
  • 按钮、链接、菜单项需加粗：
    Click **Save**
    ，而非
    Click `Save`
  • 设置路径中的每个分段需加粗，
    >
    保持原样：
    **Settings** > **AI** > **Knowledge**
语气语调
  • 使用第二人称："you can"、"allows you to"
  • 使用主动语态："Warp indexes your codebase" — 而非"your codebase is indexed"
  • 避免使用"simple"、"easy"、"just"——这些词汇会忽视读者的体验
  • 描述工作原理时使用一般现在时；给出指令时使用祈使语气
前置描述
  • 撰写为独立摘要，适合作为搜索结果片段
  • 以用户收益开头，包含功能名称和关键词
  • ✅ 
    Environments ensure your cloud agents run with a consistent toolchain. Learn when to use environments and how to configure them.
  • ❌ 
    This page describes environments.
提示框语法（Astro Starlight）
  • :::note
    — 补充背景、提示
  • :::caution
    — 注意事项、限制条件
  • :::danger
    — 破坏性或不可逆操作
  • :::tip
    — 预期结果确认
需保留为
[TODO: docs reviewer — ...]
占位符的内容
  • 计算机操作无法达到质量要求、不可用，或功能尚未发布时的截图
  • 视频/GIF嵌入
  • 若功能尚未发布，准确的设置路径
  • 最终URL路径（由文档团队确认放置位置）
  • 工程师确认后仍未验证的任何行为

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

步骤4.5：通过计算机操作捕获截图（若可用）

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.
生成草稿后，尝试通过计算机操作捕获
[TODO: docs reviewer — screenshot needed]
占位符对应的截图。此步骤为可选——仅当
computer_use
工具可用时执行。若计算机操作不可用，保留所有占位符不变。

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.
仅在满足以下所有条件时尝试捕获截图：
  • 功能已发布（未处于功能标志后或未发布状态）
  • 可通过编程方式可靠地导航到目标UI状态
  • 占位符指定了具体的UI界面（而非模糊描述，如“展示功能运行情况”）
跳过需要特定账户状态、特定数据或会暴露敏感信息的截图。

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.
捕获任何截图前：
  1. 以固定窗口大小启动Warp（使用
    warp-internal-computer-use
    技能获取启动指南）
  2. 导航到相关UI界面或触发相关功能状态
  3. 等待所有动画完成，UI完全稳定
  4. 关闭所有与待文档功能无关的弹窗、通知或提示框
  5. 关闭所有与本次截图无关的侧边栏面板
  6. 验证无敏感数据可见：检查是否存在令牌、API密钥、私有仓库名称、客户工作区数据、电子邮件地址或个人信息。若存在任何敏感数据，请勿捕获截图。

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 longer for the UI to settle, then re-capture and re-verify.
If the second attempt also fails → discard the screenshot and leave the 
[TODO: docs reviewer — screenshot]
placeholder. Do not include a screenshot you can't verify.
Step 4: Quality gate — final check before including
  • Text in the screenshot is legible at the target display size
  • The documented UI element is clearly the focal point — not buried, cropped out, or obscured
  • No sensitive data is visible (tokens, private repos, personal info, customer data)
  • UI is in a stable, non-loading state — no spinners, skeleton screens, or transitional states
  • Screenshot matches the capture expectation stated before capture
  • The screenshot would make sense at its target rendered width without looking blurry or oversized
If any item fails, discard the screenshot and leave the 
[TODO: docs reviewer — screenshot]
placeholder.
Maximum attempts per screenshot: 2. If both fail, move on.
这是一个结构化的自我验证循环。请勿跳过——这是防止状态错误、裁剪错误和取景错误的主要保障。
步骤1：捕获前说明预期
捕获任何截图前，写下你预期看到的内容：
捕获预期
  主题:            [待文档化的特定UI元素或界面]
  预期元素:  [必须可见的2-3个特定内容——例如面板标题、按钮、特定设置]
  预期状态:     [UI状态——例如“设置面板已打开”、“模态框可见”、“功能已激活并显示输出”]
  不得包含:   [任何不得可见的内容——例如敏感数据、无关弹窗、加载动画]
步骤2：捕获
捕获截图。
步骤3：查看并对照预期验证
通过计算机操作查看捕获的图像，然后对照预期检查：
  • 所述主题是否可见且明确为焦点？
  • 所有预期元素是否都存在？
  • UI是否处于预期状态（而非过渡或加载状态）？
  • 是否存在不得包含的内容？
  • 文本在目标显示宽度下是否清晰可读？
若全部通过→进入质量检查环节。
若有任何一项失败→重试一次：重新导航到UI状态，等待更长时间直至UI稳定，然后重新捕获并验证。
若第二次尝试仍失败→丢弃该截图，保留
[TODO: docs reviewer — screenshot]
占位符。请勿包含无法验证的截图。
步骤4：质量检查——纳入前的最终检查
  • 截图中的文本在目标显示尺寸下清晰可读
  • 待文档化的UI元素明确为焦点——未被隐藏、裁剪或遮挡
  • 无敏感数据可见（令牌、私有仓库、个人信息、客户数据）
  • UI处于稳定、非加载状态——无加载动画、骨架屏或过渡状态
  • 截图与捕获前说明的预期一致
  • 截图在目标渲染宽度下清晰合理，不会模糊或过大
若有任何一项失败，丢弃该截图，保留
[TODO: docs reviewer — screenshot]
占位符。
每张截图最多尝试2次。若两次均失败，继续下一步。

Sizing — choose the closest standard width

尺寸——选择最接近的标准宽度

  • Full-width (default) — full-window captures, broad product surfaces, layouts where surrounding context matters
  • ~375px — narrow UI surfaces: popovers, command menus, side panes, dropdowns, focused interaction flows
  • ~300–350px — tightly cropped controls, chips, buttons, tooltips, small menus
Crop unnecessary empty space before sizing. Keep sequences of screenshots in the same section at the same width.
  • 全宽（默认）——全窗口捕获、广泛的产品界面、需要周边上下文的布局
  • ~375px——窄UI界面：弹出框、命令菜单、侧边面板、下拉菜单、聚焦交互流程
  • ~300–350px——紧密裁剪的控件、标签、按钮、提示框、小型菜单
调整尺寸前裁剪不必要的空白区域。同一章节中的系列截图保持相同宽度。

Placement — where to insert the screenshot in the MDX

放置位置——MDX中插入截图的位置

Insert each screenshot:
  • Immediately after the paragraph that introduces the UI or state it shows
  • Near configuration instructions — show settings panels or menus where users make choices
  • Near status or result explanations — show completion states or outputs that help users recognize success
  • At the start of a visual feature page — use a broad orientation screenshot early
Do not add a screenshot for every step in a procedure. Only add one where the visual genuinely aids comprehension.
插入每张截图时：
  • 紧随介绍该UI或状态的段落之后
  • 靠近配置说明——展示用户进行选择的设置面板或菜单
  • 靠近状态或结果说明——展示帮助用户识别成功的完成状态或输出
  • 在可视化功能页面开头——尽早使用一张宽泛的导向截图
请勿为操作流程中的每一步添加截图。仅在视觉内容确实有助于理解时添加。

MDX format

MDX格式

mdx
<figure>
  <img
    src="../../../assets/<section>/<feature-name>-<ui-state>.png"
    alt="[Descriptive alt text: what the image shows, not just 'screenshot']"
  />
  <figcaption>[Caption: complete sentence, ≤10 words, orient don’t instruct, no marketing language, sentence case, ends with period.]</figcaption>
</figure>
Alt text rules:
  • Describe what the image shows, not just "screenshot"
  • ✅ 
    alt="Agent permissions settings with 'Always allow' selected for file reads"
  • ❌ 
    alt="screenshot"
    or 
    alt=""
Caption rules:
  • Orient the reader — describe what is shown, not what to do
  • Complete sentence, ≤10 words ideally, never exceed ~20 words
  • No marketing language (avoid "easily," "quickly," "powerful," "at a glance")
  • Don't repeat the prose — the caption adds context, not an echo
  • Don't list everything visible — name the subject
  • ✅ 
    <figcaption>The Environments page in the Oz web app.</figcaption>
  • ❌ 
    <figcaption>Click the toast to jump to the agent’s session.</figcaption>
    (procedural — put this in body text)
File naming: lowercase, hyphens, descriptive — e.g. 
agent-mode-permissions-panel.png
File location: Save PNGs to 
src/assets/<section>/
in 
warpdotdev/docs
(Astro optimizes them automatically).
mdx
<figure>
  <img
    src="../../../assets/<section>/<feature-name>-<ui-state>.png"
    alt="[描述性替代文本：说明图像内容，而非仅写‘screenshot’]"
  />
  <figcaption>[标题：完整句子，≤10个单词，仅说明内容而非指令，无营销语言，句首大写，以句号结尾。]</figcaption>
</figure>
替代文本规则：
  • 说明图像内容，而非仅写‘screenshot’
  • ✅ 
    alt="Agent permissions settings with 'Always allow' selected for file reads"
  • ❌ 
    alt="screenshot"
    或 
    alt=""
标题规则：
  • 为读者提供导向——说明展示的内容，而非操作指令
  • 完整句子，理想情况下≤10个单词，绝不超过约20个单词
  • 无营销语言（避免使用‘easily’、‘quickly’、‘powerful’、‘at a glance’）
  • 不要重复正文内容——标题补充背景，而非重复
  • 不要列出所有可见内容——只需说明主题
  • ✅ 
    <figcaption>The Environments page in the Oz web app.</figcaption>
  • ❌ 
    <figcaption>Click the toast to jump to the agent’s session.</figcaption>
    （操作指令——应放入正文中）
文件命名：小写、短横线分隔、描述性名称——例如
agent-mode-permissions-panel.png
文件位置：将PNG保存到
warpdotdev/docs
仓库的
src/assets/<section>/
目录（Astro会自动优化）。

Step 5: Open the draft PR

步骤5：打开草稿PR

After generating the draft, submit it to 
warpdotdev/docs
automatically:
  1. Clone 
    warpdotdev/docs
    to a temp directory (or use the local clone if available)
  2. Write the MDX file to 
    src/content/docs/<proposed-section>/<filename>.mdx
  3. Add a placeholder entry to 
    src/sidebar.ts
    under the appropriate section (mark it 
    [TODO: docs reviewer — confirm placement]
    )
  4. Commit and push on a new branch named 
    docs/<spec-id>-feature-draft
  5. Open a draft PR in 
    warpdotdev/docs
    with a description that includes:
    • The feature name and spec ID
    • A link to the original spec PR
    • A list of all 
      [UNVERIFIED]
      and 
      [TODO]
      items in the draft for reviewer attention
  6. Request review from 
    @rachaelrenk
    , 
    @petradonka
    , and 
    @hongyi-chen
生成草稿后，自动提交到
warpdotdev/docs
仓库：
  1. 将
    warpdotdev/docs
    克隆到临时目录（若有本地克隆则使用）
  2. 将MDX文件写入
    src/content/docs/<proposed-section>/<filename>.mdx
  3. 在
    src/sidebar.ts
    的对应章节下添加占位符条目（标记为
    [TODO: docs reviewer — confirm placement]
    ）
  4. 在名为
    docs/<spec-id>-feature-draft
    的新分支上提交并推送
  5. 在
    warpdotdev/docs
    中打开草稿PR，描述需包含：
    • 功能名称和规范ID
    • 原始规范PR的链接
    • 草稿中所有
      [UNVERIFIED]
      和
      [TODO]
      项的列表，供审核者关注
  6. 请求
    @rachaelrenk
    、
    @petradonka
    和
    @hongyi-chen
    进行审核

No-spec fallback

无规范 fallback

If 
specs/<id>/PRODUCT.md
and 
specs/<id>/TECH.md
don't exist, research the codebase first before interviewing the engineer.
Research steps:
  1. Search 
    warpdotdev/warp-internal
    (or 
    warp-server
    depending on context) for the feature name and related terms: 
    gh search code "<feature-name>" --repo warpdotdev/warp-internal
  2. Read the most relevant source files to understand what the feature does
  3. Check for spec files under a different ID: 
    gh api repos/warpdotdev/warp-internal/git/trees/HEAD?recursive=1 | grep -i spec
  4. Review recent merged PRs related to the feature: 
    gh pr list --search "<feature-name>" --state merged --repo warpdotdev/warp-internal --limit 10
After research, build as complete a picture as possible, then use 
ask_user_question
only for specific gaps you couldn't fill from the code — not as a broad interview. Frame the questions concretely: "I found the feature in 
app/src/ai/
. Based on the code, here's what I understand: [summary]. I couldn't determine these two things: [specific questions]."
Build the outline from your research and the engineer's targeted answers, then proceed to Step 3 (outline confirmation) before drafting.
若
specs/<id>/PRODUCT.md
和
specs/<id>/TECH.md
不存在，先研究代码库再与工程师沟通。
研究步骤：
  1. 在
    warpdotdev/warp-internal
    （或根据上下文选择
    warp-server
    ）中搜索功能名称及相关术语：
    gh search code "<feature-name>" --repo warpdotdev/warp-internal
  2. 阅读最相关的源文件，了解功能作用
  3. 检查是否存在其他ID下的规范文件：
    gh api repos/warpdotdev/warp-internal/git/trees/HEAD?recursive=1 | grep -i spec
  4. 查看与该功能相关的近期合并PR：
    gh pr list --search "<feature-name>" --state merged --repo warpdotdev/warp-internal --limit 10
研究完成后，尽可能构建完整的功能图景，然后仅针对无法从代码中填补的特定空白使用
ask_user_question
——而非进行宽泛的访谈。问题需具体：“我在
app/src/ai/
中找到了该功能。根据代码，我的理解是：[摘要]。我无法确定以下两点：[具体问题]。”
根据你的研究和工程师的针对性回答构建大纲，然后进入步骤3（大纲确认）再开始起草。

Ambient mode (called by scan-new-specs)

环境模式（由scan-new-specs调用）

When this skill is invoked by 
scan-new-specs
rather than an engineer directly, it runs in ambient mode — there is no interactive terminal session, so the outline confirmation step must be handled differently.
In ambient mode:
  1. Complete Steps 1 and 2 (read spec, research codebase) as normal
  2. Skip the interactive outline confirmation. Instead, embed the outline directly in the PR description as a checklist:
markdown
undefined
当此技能由
scan-new-specs
而非工程师直接调用时，它将以环境模式运行——无交互式终端会话，因此大纲确认步骤需以不同方式处理。
在环境模式下：
  1. 正常完成步骤1和2（阅读规范、研究代码库）
  2. 跳过交互式大纲确认。改为将大纲作为检查表直接嵌入PR描述中：
markdown
undefined

Docs outline (auto-generated)

文档大纲（自动生成）

The following outline was generated from the spec. @<github-username>: please review and check off each item, or leave a comment with corrections.
以下大纲由规范生成。@<github-username>：请审核并勾选每一项，或留下修正意见。

Content structure

内容结构

  • H1: 
    <feature name>
  • Opening paragraph describes: [your 1-sentence summary]
  • Key features section covers: [which capabilities]
  • How it works section covers: [the conceptual model]
  • ## <Usage section>
    with steps: [numbered list]
  • Related pages: [suggested cross-links]
  • 一级标题: 
    <feature name>
  • 开篇段落描述: [你的一句话摘要]
  • 核心功能章节涵盖: [哪些功能]
  • 工作原理章节涵盖: [概念模型]
  • ## <使用章节>
    包含步骤: [编号列表]
  • 相关页面: [建议的交叉链接]

Items needing engineer verification ⚠️

需工程师验证的项目 ⚠️

  • [UNVERIFIED item 1 — e.g. "Does this trigger automatically or require manual action?"]
  • [UNVERIFIED item 2]
  • [未验证项1 — 例如：“这是自动触发还是需要手动操作？”]
  • [未验证项2]

Verified from codebase ✅

已从代码库验证 ✅

  • [What was confirmed, e.g. "Feature flag: 
    my_feature
    in warp-internal"]

3. Generate the full MDX draft (Step 4) with this constraint: **do not draft any content derived from `TECH.md` in ambient mode.** There is no engineer present to confirm what is confidential, so any detail that came exclusively from `TECH.md` (implementation internals, data model, server architecture, private API details) must be replaced with `[TODO: engineer to verify — pulled from TECH.md, confirm this is safe to publish]`. Only `PRODUCT.md` content and codebase-verified facts are safe to draft without confirmation.
4. **Attempt screenshots** (Step 4.5) — if computer use is available, run the predict-then-verify capture protocol for any screenshot placeholders. Include any screenshots that pass the quality gate in the draft.
5. Open the draft PR (Step 5) as normal — tag the spec author and docs reviewers
6. Do not post any interactive messages to the terminal; all output should go into the PR

---
  • [已确认内容，例如：“功能标志：
    my_feature
    在warp-internal中”]

3. 生成完整的MDX草稿（步骤4），需遵守以下限制：**环境模式下请勿起草任何源自`TECH.md`的内容**。由于没有工程师在场确认哪些内容是保密的，任何仅来自`TECH.md`的细节（实现内部、数据模型、服务器架构、私有API细节）必须替换为`[TODO: engineer to verify — pulled from TECH.md, confirm this is safe to publish]`。只有`PRODUCT.md`的内容和从代码库验证的事实可以无需确认直接起草。
4. **尝试捕获截图**（步骤4.5）——若计算机操作可用，对任何截图占位符执行预测-验证捕获流程。将通过质量检查的截图纳入草稿。
5. 正常打开草稿PR（步骤5）——标记规范作者和文档审核者
6. 请勿向终端发送任何交互式消息；所有输出应放入PR中

---

Related skills

相关技能

  • write-product-spec
    — produces the 
    PRODUCT.md
    this skill reads
  • write-tech-spec
    — produces the 
    TECH.md
    this skill reads
  • scan-new-specs
    — the scheduled agent that invokes this skill in ambient mode
  • write-product-spec
    — 生成此技能读取的
    PRODUCT.md
  • write-tech-spec
    — 生成此技能读取的
    TECH.md
  • scan-new-specs
    — 在环境模式下调用此技能的定时Agent