write-feature-docs

write-feature-docs

为 Warp 的新功能起草一篇完整的文档页面。你需要阅读功能规格，亲自研究代码库以核实技术说法，与工程师确认内容设计方案，然后确认大纲，最后才编写完整的 MDX 草稿，并在 warpdotdev/docs 中创建草稿 PR，邀请文档团队审核。

工程师的职责是确认你无法通过规格和代码核实的内容，而不是全面审核准确性、润色文案或了解文档规范。

工作流

1. 查找并阅读规格文件
2. 研究代码库以核实技术说法，尽量减少需要工程师检查的内容
3. 提交内容设计方案并等待确认——页面面向哪些读者
4. 提交大纲并等待确认——页面将包含哪些内容
5. 生成完整的 MDX 草稿 5.5. 尝试通过计算机操作截取屏幕截图（如可用）
6. 在 warpdotdev/docs 中创建草稿 PR，并邀请文档团队

第 3 步和第 4 步是按顺序进行的两次独立确认。大纲应根据方案制定——方案决定内容类型，而内容类型决定大纲包含哪些章节。一起提交会让工程师看到一份基于尚未达成共识的读者群体所制定的大纲，他们会先入为主地关注具体大纲，而不是重新考虑更上层的问题。先确定页面面向哪些读者，再决定页面包含什么内容。

---

第 1 步：查找并阅读规格

如果工程师尚未提供规格 ID，请向其询问。规格 ID 可以是以下之一：

• Linear 工单编号：APP-1234、REMOTE-1234、QUALITY-408
• GitHub issue（前缀为 gh-）：gh-4567
• 简短的 kebab-case 功能名称：vertical-tabs-hover-sidecar

在以下位置查找规格文件：

• specs/<id>/PRODUCT.md — 主要来源：面向用户的行为、内容及原因
• specs/<id>/TECH.md — 次要来源：实现方式、数据模型

如果两个文件都存在，请同时阅读。PRODUCT.md 是文档内容的主要依据。

阅读 TECH.md 时： 在纳入其中任何内容之前，先找出看起来属于内部实现细节的内容，例如数据库架构、内部服务名称、私有 API 端点和机密服务器架构。向工程师列出这些标记内容，并请他们确认哪些可以安全地写入公开文档，哪些应保留为内部信息。不得在草稿中包含任何标记为机密的内容。

因此，这项技能要求工程师必须在场。不存在无人值守的流程：没有人确认哪些内容可以公开，就不能起草任何 TECH.md 中的内容。

如果两个文件都不存在，请跳转到无规格回退方案。

---

第 2 步：研究代码库

在提交方案或大纲之前，使用 GitHub CLI 尽可能核实所有技术内容，从而将需要工程师确认的内容减少到你确实无法从代码中确定的部分。 需要从代码中核实的内容：

• 功能标志名称：从规格说明标题或工单中查找安全的功能标记。使用任何 shell 命令之前，先将其缩减为符合 ^[A-Za-z0-9][A-Za-z0-9_-]*$ 的允许列表标记；如果无法安全生成，则跳过 shell 搜索；随后运行 FEATURE_TOKEN="<validated-token>" && gh search code "${FEATURE_TOKEN}" --repo warpdotdev/warp-internal。
• UI 字符串：搜索规格说明中提到的面向用户的按钮标签、菜单项名称或设置名称
• 设置路径：确认准确的 Settings 菜单路径（例如，**Settings** > **AI** > **Knowledge**）
• 规格说明中提到的 CLI 命令或键盘快捷键
• 相关功能：找出在“相关页面”中交叉引用此功能的其他功能
• 要标记的工程师：确定负责该规格说明的工程师的 GitHub 用户名。
  • 交互模式：运行 gh api user --jq .login，获取当前运行此技能的人员的用户名 — 仅当直接由规格说明工程师调用此技能时使用此方法。如果运行此技能的是文档团队成员或非作者，请改用以下发现步骤。
  • 非作者运行（文档团队成员或未编写规格说明的任何人）：运行任何查询命令之前，验证规格 ID 仅包含字母数字字符和连字符（匹配 ^[A-Za-z0-9][A-Za-z0-9-]*$）。如果规格 ID 包含其他字符，则完全跳过查询，并使用 [TODO: tag spec author] 作为占位符。如果规格 ID 有效，将其赋给 SPEC_ID，并按顺序执行以下步骤，一旦找到用户名即停止：
    1. 检查提交消息中的 Co-authored-by: 尾注 — 在从私有源同步的仓库（如 warp-internal）中，同步机器人是提交作者，但真实作者会出现在 Co-authored-by: 尾注中。提取第一个非机器人的条目：

       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 '<>'
       

       这会返回一个电子邮件地址（可能是 GitHub noreply 地址）。如果该电子邮件地址符合 <userid>+<username>@users.noreply.github.com 格式，则直接提取用户名：echo "$EMAIL" | grep -oP '\+\K[^@]+'。如果是真实电子邮件地址，则通过 gh api "search/users?q=${EMAIL}+in:email" --jq '.items[0].login' 查询。
    2. 解析同步来源 PR URL — 有些同步机器人会在提交正文中嵌入原始 PR URL（例如 Synced from warp: https://github.com/warpdotdev/warp/pull/11901）。提取该 URL 并获取 PR 作者：

       ORIG_PR=$(git log --follow -1 --format="%B" -- "specs/${SPEC_ID}/PRODUCT.md" \
         | grep -oP 'https://github\.com/[^/]+/[^/]+/pull/\d+' | head -1)
       # 提取所有者/仓库和 PR 编号，然后运行：gh pr view <N> --repo <owner/repo> --json author --jq '.author.login'
       

    3. 搜索源仓库中的 PR — 尝试实际拥有该代码的仓库（如果可以访问，同时检查公开镜像和私有源）：

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

       跳过用户名包含 [bot] 的任何结果。
    4. 回退到提交作者的电子邮件地址 — 仅当电子邮件地址不包含 [bot] 时使用：

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

       如果 ${EMAIL} 非空且不含机器人标记，则通过 gh api "search/users?q=${EMAIL}+in:email" --jq '.items[0].login' 查询用户名。
    5. 如果完成所有步骤后仍未找到用户名，则在 PR 正文中使用 [TODO: tag spec author] 作为占位符。 你每次从代码中核实一项声明，都将其标记为已确认。对于无法核实的声明（代码中未体现的 UI 行为、产品意图、尚未发布的功能行为），在大纲中将其标记为 [UNVERIFIED]——这些才是工程师需要重点关注的内容。

---

步骤 3：展示内容设计计划并等待

这是两次确认中的第一次，且必须在大纲之前进行。 在决定页面要包含什么之前，先确定页面面向谁。

根据文档仓库中的 .agents/references/content-design-plan.md 对各字段的说明，填写 .agents/templates/content-design-plan.md 中的内容：受众和 JTBD、问题、目标、目的和价值、内容类型、技能和模板，以及明确排除项的高影响场景。

将其打印到终端，然后说：

“在我列出页面大纲之前，请确认读者和他们要完成的任务是否正确。请修正不准确之处，或回复‘看起来不错’，我就会起草大纲。”

等待工程师回复。 不要在同一条消息中生成大纲。计划决定内容类型，内容类型决定大纲包含哪些部分——如果计划尚未确认就同时展示大纲，会让工程师关注眼前具体的章节，而不是先审视上面设定的受众。

如果他们更改了受众、内容类型或范围，请修订计划并重新确认，然后再继续。将已确认的计划纳入步骤 6 的 PR 正文。

---

步骤 4：展示大纲并等待

根据步骤 3 中已确认的计划，生成简洁的大纲——不写正文。大纲要展示你通过调研确认的内容，以及仍需工程师提供意见的具体事项。

按以下格式将大纲打印到终端：

📄 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
  title:  <Feature name>   (frontmatter; Starlight renders it as the H1)
  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]

上述章节只是默认设置。请根据功能调整大纲：如果功能不需要概念说明，就省略 ## How it works；如果功能有不同的工作流，就添加多个使用章节；如果功能足够简单，就将 ## Key features 合并到开篇段落中。

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?"]

打印大纲后，说：

“我已核实了能从代码库中确认的内容。请检查上方标记为 ⚠️ 的项目，并回复任何修正意见；如果一切无误，请回复‘看起来不错’以继续。”

在继续之前，等待工程师回复。采纳他们的反馈，然后起草文档。

如果他们的反馈与步骤 3 中已确认的计划相矛盾——例如读者或内容类型有所不同——也要修订计划，避免两者脱节。计划会被放入 PR 正文，因此过时的计划会误导审阅者。

---

步骤 5：生成 MDX 草稿

根据已确认的大纲生成完整的 .mdx 文件。输出应可直接放入 warpdotdev/docs。

模板结构

使用计划所选内容类型的规范模板，该模板位于文档仓库的 .agents/templates/ 中：feature-doc.md、conceptual.md、procedural.md、reference.md、troubleshooting.md、quickstart.md 或 guide-page.md。这些模板是权威依据，并附有逐字段说明。下面的示意展示了最常见的类型之一——功能文档——大致长什么样，便于你了解预期格式；它不能替代对实际模板的阅读。

模板有两条要求很容易凭记忆弄错：页面标题必须放在前置元数据中，而不是正文的 H1 标题里（Starlight 会将前置元数据中的标题渲染为 H1，因此正文中的 H1 会造成重复）；页面发布前必须删除所有方括号括起的说明。

---
title: [Feature name — sentence case]
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.]
---

[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)

样式规则 — 请严格遵守

这些规范来自 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**

语态和语气

• 使用第二人称：“你可以”“让你能够”
• 使用主动语态：“Warp 会为你的代码库编制索引”，不要写成“你的代码库会被编制索引”
• 避免使用“简单”“容易”“只需”等词语，以免轻视读者的体验
• 描述功能如何运作时使用现在时；提供说明时使用祈使语气

Frontmatter 描述

• 撰写可作为搜索结果摘要独立使用的概述
• 以用户收益为先，包含功能名称和关键术语
• ✅ 环境可确保你的云 Agent 使用一致的工具链运行。了解何时使用环境以及如何配置环境。
• ❌ 本页介绍环境。

Callout 语法（Astro Starlight）

• :::note — 补充说明、提示
• :::caution — 注意事项、限制
• :::danger — 破坏性或不可逆操作
• :::tip — 实用提示和最佳实践

应保留为 [TODO: docs reviewer — ...] 占位符的内容

• 使用计算机时无法通过质量门槛、不可用或功能尚未发布的截图
• 视频/GIF 嵌入内容
• 功能尚未发布时的准确设置路径
• 最终 URL 路径（由文档团队确认位置）
• 工程师确认后仍未验证的任何行为

---

第 5.5 步：通过计算机操作捕获截图（如可用）

生成草稿后，尝试通过计算机操作为任何 [TODO: docs reviewer — screenshot needed] 占位符捕获截图。此步骤为可选——仅当 computer_use 工具可用时才执行。如果无法使用计算机操作，请保留所有占位符。

决定尝试捕获哪些截图

仅当以下条件全部满足时才尝试捕获截图：

• 功能已发布（并非处于功能标志控制下或尚未发布）
• 可以通过程序可靠地导航到相应 UI 状态
• 占位符指定了具体的 UI 界面（而非“展示功能的运行效果”等模糊描述）

跳过需要特定账户状态、特定数据或可能暴露敏感信息内容的截图。

捕获前准备

捕获任何截图之前：

1. 以一致的窗口大小启动 Warp（参阅 warp-internal-computer-use 技能获取启动指南）
2. 导航到相关 UI 界面，或触发相关功能状态
3. 等待所有动画完成，并确保 UI 完全稳定
4. 关闭任何与文档内容无关的弹出窗口、通知或临时提示
5. 关闭与此截图无关的侧边栏面板或窗格
6. 确认画面中没有敏感数据：检查是否显示令牌、API 密钥、私有仓库名称、客户工作区数据、电子邮件地址或个人信息。如果显示了任何此类内容，请勿截图。

截图协议：预测 → 截图 → 验证 → 再试一次

这是一个结构化的自我验证循环。请勿跳过——这是防止截图状态错误、裁剪错误和取景错误的主要保障。

步骤 1：截图前说明预期内容

截取任何屏幕截图之前，先写下预期看到的内容：

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]

步骤 2：截图

截取屏幕截图。

步骤 3：查看并根据预期进行验证

使用计算机操作查看截取的图像，然后根据预期进行检查：

• 是否能看到所述的主体，并且主体明显是视觉焦点？
• 是否包含所有预期元素？
• UI 是否处于预期状态（而非过渡状态或加载状态）？
• 是否能看到任何不得包含的内容？
• 文字在目标显示宽度下是否清晰可读？

如果全部通过 → 进入质量检查关卡。

如果有任何一项未通过 → 再尝试一次：重新导航到 UI 状态，等待 UI 更充分地稳定下来，然后重新截图并验证。

如果第二次尝试仍未通过 → 舍弃该屏幕截图，并保留 [TODO: docs reviewer — screenshot] 占位符。不要加入无法验证的屏幕截图。

步骤 4：质量检查关卡 — 纳入前的最终检查

• 屏幕截图中的文字在目标显示尺寸下清晰可读
• 文档中说明的 UI 元素是明显的视觉焦点——没有被埋没、裁掉或遮挡
• 没有显示敏感数据（令牌、私有代码仓库、个人信息、客户数据）
• UI 处于稳定的非加载状态——没有旋转指示器、骨架屏或过渡状态
• 屏幕截图符合截图前说明的预期
• 屏幕截图以目标渲染宽度显示时效果清晰，大小也合适

如果任何一项未通过，请舍弃屏幕截图并保留 [TODO: docs reviewer — screenshot] 占位符。

每张屏幕截图最多尝试 2 次。 如果两次都失败，请继续处理下一项。

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

• 全宽（默认） — 全窗口截图、宽阔的产品界面、需要周围上下文的布局
• ~375px — 窄小的 UI 界面：弹出框、命令菜单、侧边窗格、下拉菜单、专注于交互的流程
• ~300–350px — 紧凑裁剪的控件、标签、按钮、工具提示、小型菜单

调整尺寸前，先裁掉不必要的空白。同一章节中的一组屏幕截图应保持相同宽度。

插入位置 — 在 MDX 中插入屏幕截图的位置

插入每张屏幕截图时：

• 放在介绍对应 UI 或所示状态的段落之后
• 放在配置说明附近——展示用户进行选择时看到的设置面板或菜单
• 放在状态或结果说明附近——展示有助于用户识别成功的完成状态或输出
• 放在视觉功能页面的开头——尽早提供概览截图

不要为流程中的每个步骤都添加屏幕截图。仅在视觉内容确实有助于理解时添加。

MDX 格式

<figure>
  <img
    src="[relative path from this MDX file to src/assets/<section>/<feature-name>-<ui-state>.png — count the directory depth of the MDX file and use that many ../ levels; e.g. 3 levels deep → ../../../assets/<section>/...]"
    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="Agent permissions settings with 'Always allow' selected for file reads"
• ❌ alt="screenshot" 或 alt=""

说明文字规则：

• 帮助读者了解所示内容，而非说明操作方法
• 使用完整句子，最好不超过 10 个词，绝不超过约 20 个词
• 不使用营销语言（避免“轻松”“快速”“强大”“一目了然”）
• 不要重复正文——说明文字应补充上下文，而非简单复述
• 不要罗列所有可见内容——点明主体即可
• ✅ <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 会自动优化这些文件。

---

第 6 步：打开草稿 PR

打开 PR 前，请确认已满足文档仓库自身的要求。 warpdotdev/docs 会根据两项要求审核新提交的页面，若 PR 未满足这些要求，就会被退回：

1. 文档仓库中的 .agents/references/docs-worthiness-criteria.md 的 Gate 0：此功能是否已发布并正式上线（GA），且面向公开用户？如果不是，就不要打开 PR——告诉工程师原因，然后停止。即使工程师要求编写此页面，也值得确认这一点，因为为尚未发布的功能编写文档是最常见的问题，而且工程师比用户更接近开发进度，很容易比用户提前一个版本。

   此参考文档中的其余门槛，属于判断某项变更是否值得编写文档的考量。它们用于约束自动化流程，而非你——要求为自己已发布功能编写文档的工程师，掌握门槛无法获知的背景信息。不要以这些理由拒绝。

2. 工程师在第 3 步确认的内容设计方案，必须作为 ## Content design plan 部分写入 PR 正文。

只要已有页面涵盖相关内容，就应优先更新现有页面，而不是创建新页面。

生成草稿后，将其提交到 warpdotdev/docs：

1. 将 warpdotdev/docs 克隆到临时目录（如果有本地克隆，也可以使用本地克隆）

2. 将 MDX 文件写入 src/content/docs/<proposed-section>/<filename>.mdx

3. 在 src/sidebar.ts 的相应部分下添加占位条目。示例：

   // [TODO: docs reviewer — confirm placement]
   { label: '<Feature name>', link: '/<section>/<feature-name>/' },
   

4. 在新分支上提交并推送，分支名为 docs/<spec-id>-feature-draft

5. 先将 PR 正文写入临时文件，再使用 --body-file 打开草稿 PR。PR 描述必须包含：

   • 功能名称和 spec ID
   • 原始 spec PR 的链接
   • 草稿中所有 [UNVERIFIED] 和 [TODO] 项的列表，供审核者留意

   使用可用的任意文件写入方式（文件创建工具、Python 的 open() 调用，或带引号的 shell heredoc）将正文写入 /tmp/pr-body.md，然后将文件传给 gh：

   gh pr create --draft --body-file /tmp/pr-body.md ...
   

   绝不要以内联方式传递 PR 正文（例如使用 --body "..."、echo，或将 printf 的输出直接通过管道传给 gh）。在字符串到达 gh 之前，shell 字符串插值会展开反引号、$vars 和 [ ] 通配模式，从而破坏包含这些字符的 Markdown。先写入文件即可避免 shell 对内容进行任何解析。

   在 PR 正文的“Docs outline”部分，已由 Agent 验证的条目使用普通项目符号（-），不要使用 - [x] 复选框。仅在“Items needing review”部分使用 - [ ] 复选框，让审核者清楚知道哪些事项需要他们处理。

6. 在 PR 正文中，使用第 2 步获得的用户名提醒 spec 作者：

   • 如果找到有效的 GitHub 用户名：添加 /cc @<engineer-handle>
   • 如果使用了备用占位文本：添加原样文本 [TODO: tag spec author]——不要将其写成 /cc @ 的形式，否则会生成无效提及 请求 @rachaelrenk 和 @hongyi-chen 进行审核。

---

无规格说明时的回退方案

如果 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/contents/specs
4. 查看与该功能相关的近期已合并 PR：gh pr list --search "<feature-name>" --state merged --repo warpdotdev/warp-internal --limit 10

**研究完成后，**尽可能全面地了解情况，然后仅针对无法通过代码查明的具体问题使用 ask_user_question，不要进行宽泛的采访。问题要具体明确：“我在 app/src/ai/ 中找到了这个功能。根据代码，我的理解如下：[摘要]。有两点我无法确定：[具体问题]。”

根据研究结果和工程师有针对性的回答制定计划和大纲，然后完成步骤 3（确认计划）和步骤 4（确认大纲），再开始起草。

---

仅限交互模式——没有无人值守模式

此技能之前有一种“环境模式”，允许 scan-new-specs 在无头模式下驱动它，跳过步骤 3 和 4 中的确认，并将大纲作为清单嵌入 PR 描述。该模式已移除，scan-new-specs 已停用。

这种模式曾为尚未发布的功能创建草稿 PR，因为规格说明已合并不代表功能已发布，而无人值守运行无法分辨两者。跳过大纲确认也移除了唯一一个可以让人类在撰写正文之前调整草稿的检查点。

不要在此处重新添加无人值守流程：

• **对于由发布触发的自动化文档，**请使用 warpdotdev/docs 仓库中的 missing_docs。它会在起草前根据 .agents/references/docs-worthiness-criteria.md 筛选每个候选项，并且只在新的稳定版本发布后运行。
• **对于希望为其功能编写文档的工程师，**此技能是合适的工具——直接调用，并由工程师确认大纲和 TECH.md 的范围。

如果你在没有交互会话的情况下运行，请停止并说明此技能需要交互会话，而不要继续起草。

---

相关技能

• write-product-spec — 生成此技能读取的 PRODUCT.md
• write-tech-spec — 生成此技能读取的 TECH.md
• missing_docs（位于 warpdotdev/docs）— 面向新发布功能、由发布触发且经过价值筛选的文档流水线
• scan-new-specs — 已停用；请参阅其弃用通知