工程师已写功能 spec、需要为 Warp 新功能产出首版…

适用于有工程师在场、先确认内容设计计划和大纲，再基于 spec 与代码研究为 Warp 功能生成文档页面草稿的交互式工作流。

适用场景

解决思路

1. 1. 向工程师索要 spec ID（Linear ticket 如 `APP-1234`、GitHub issue 如 `gh-4567`、kebab-case feature name 如 `vertical-tabs-hover-sidecar`），并查找和阅读 `specs/<id>/PRODUCT.md` 与 `specs/<id>/TECH.md`；`PRODUCT.md` 是主源，`TECH.md` 是次源；两者都无则进入 No-spec fallback。
2. 2. 读取 `TECH.md` 时，先标出内部实现细节（数据库 schema、内部服务名、私有 API endpoint、机密服务器架构），逐项让工程师确认哪些可公开、哪些须保密；机密内容不得写入草稿。
3. 3. 在呈现内容设计计划或大纲前，用 GitHub CLI 自行研究代码库，尽量验证技术内容，只把确实无法从代码判断的问题留给工程师。
4. 4. 验证 feature flag 名：从 spec 标题或 ticket 取安全 token；shell 使用前只允许匹配 `^[A-Za-z0-9][A-Za-z0-9_-]*$` 的 token，不安全就跳过 shell 搜索；运行 `FEATURE_TOKEN="<validated-token>" && gh search code "${FEATURE_TOKEN}" --repo warpdotdev/warp-internal`。
5. 5. 从代码验证 UI strings：搜索 spec 中提到的用户可见按钮标签、菜单项名或设置名。
6. 6. 从代码验证 Settings 路径：确认精确 Settings 菜单路径，例如 `**Settings** > **AI** > **Knowledge**`。
7. 7. 从代码验证 spec 中提到的 CLI 命令或键盘快捷键。
8. 8. 从代码识别与本功能交叉引用的相关功能，用于 `## Related pages`。
9. 9. 确定要 tag 的工程师 GitHub handle；交互模式且由 spec 工程师本人直接运行时，运行 `gh api user --jq .login` 获取当前用户 handle。
10. 10. 非作者运行（docs 团队成员或任何未写 spec 的人）时，先校验 spec ID 仅含字母数字和连字符，匹配 `^[A-Za-z0-9][A-Za-z0-9-]*$`；不匹配则跳过所有查询，并在 PR body 使用 `[TODO: tag spec author]` 占位。
11. 11. 若 spec ID 有效，赋值 `SPEC_ID`，按顺序查找 handle，找到即停：先检查 commit message 的 `Co-authored-by:` trailer；运行 `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 '<>'`，提取第一个非 bot 条目。
12. 12. 若第 11 步得到 email 且匹配 `<userid>+<username>@users.noreply.github.com`，用 `echo "$EMAIL" | grep -oP '\+\K[^@]+'` 直接提取 handle；若是真实 email，用 `gh api "search/users?q=${EMAIL}+in:email" --jq '.items[0].login'` 解析。
13. 13. 解析 synced-from PR URL：从 commit body 提取 `https://github\.com/[^/]+/[^/]+/pull/\d+`，取 owner/repo 和 PR number，然后运行 `gh pr view <N> --repo <owner/repo> --json author --jq '.author.login'`。
14. 14. 搜索 origin repo PRs：运行 `gh pr list --search "specs/${SPEC_ID}" --repo warpdotdev/warp-internal --state merged --json author --limit 1 --jq '.[0].author.login'`，也试 `--repo warpdotdev/warp`，跳过 login 含 `[bot]` 的结果。
15. 15. 回退到 commit author email：仅当 email 非空且不含 `[bot]` 时，运行 `EMAIL=$(git log --follow -1 --pretty=format:"%ae" -- "specs/${SPEC_ID}/PRODUCT.md")`，再用 `gh api "search/users?q=${EMAIL}+in:email" --jq '.items[0].login'` 解析为 handle。
16. 16. 若以上所有步骤都没找到 handle，在 PR body 使用字面 `[TODO: tag spec author]` 占位。
17. 17. 对从代码验证的 claim 标记为 confirmed；对无法验证的 claim（代码中没有的 UI 行为、产品意图、未发布功能行为）标 `[UNVERIFIED]`，这些是工程师唯一需要重点检查的内容。
18. 18. 填充 docs repo 的 `.agents/templates/content-design-plan.md`，参考 `.agents/references/content-design-plan.md` 理解字段；字段包括 audience and JTBD、problem、goals、purpose and value、content type、skill and template、high-impact scenarios 和 explicit exclusions。
19. 19. 将内容设计计划打印到终端，并说：先确认这是正确读者和正确 job，纠正或回复 `looks good` 后再画 outline；随后等待工程师回复，不要在同一条消息里产出 outline。
20. 20. 若工程师改变 audience、content type 或 scope，先修订计划并重新确认再继续；把确认后的计划带入 Step 6 的 PR body。
21. 21. 基于已确认计划生成简洁 outline（不要 prose），先写 PROPOSED PLACEMENT：Section `src/content/docs/<section>/`、File `<feature-name>.mdx`、URL `docs.warp.dev/<path>/<feature-name>`。
22. 22. outline 的 CONTENT SECTIONS 包含：frontmatter `title`、Opening paragraph、`## Key features`、`## How it works`、`## <Usage section title>`、Prerequisites、编号 Steps、`## Related pages`。
23. 23. 按功能调整 outline：不需要概念解释就省略 `## How it works`；有多个独立工作流就加多个 usage section；功能足够简单就把 `## Key features` 折叠进 opening paragraph。
24. 24. 在 outline 中列出 `VERIFIED FROM CODEBASE ✅` 项和 `NEEDS YOUR CONFIRMATION ⚠️` 项。
25. 25. 打印 outline 后说：已从代码库验证能验证的内容，请检查 ⚠️ 项并回复修正，或回复 `looks good` 继续；等待工程师回复，纳入反馈后再起草。若反馈与已确认计划矛盾（不同读者、不同 content type），连同计划一起修订，避免过期计划误导 reviewer。
26. 26. 基于已确认 outline 生成完整 `.mdx` 草稿，输出应可直接放入 `warpdotdev/docs`；使用计划所选 content type 的 canonical template：`feature-doc.md`、`conceptual.md`、`procedural.md`、`reference.md`、`troubleshooting.md`、`quickstart.md` 或 `guide-page.md`。
27. 27. 遵守模板两条规则：页面标题放 frontmatter，不放 body H1（Starlight 会把 frontmatter title 渲染成 H1）；所有括号内说明必须在发布前删除。
28. 28. 按模板结构起草：frontmatter `title` 和 `description`；opening paragraph；可选 `:::note`；`## Key features`；`## How it works` 概念节；`## [Usage section title]` 程序节；`### Prerequisites`；编号步骤；`## Related pages`。
29. 29. 标题风格：所有标题用 sentence case，只大写首词和专有功能名；专有功能名保留大小写，如 `Agent Mode`、`Warp Drive`、`Oz`、`Command Palette`。
30. 30. 列表风格：用 `* **Term** - Description`，不要用冒号。
31. 31. UI 元素和路径风格：按钮、链接、菜单项加粗，如 `Click **Save**`；Settings 路径每段加粗，`>` 保持普通，如 `**Settings** > **AI** > **Knowledge**`。
32. 32. Voice and tone：第二人称（you can、allows you to）；主动语态；避免 simple、easy、just；描述工作方式用现在时，指令用祈使句。
33. 33. Frontmatter description：写成独立摘要，能作为搜索结果 snippet；先讲用户收益，包含功能名和关键术语。
34. 34. Callout 语法用 Astro Starlight：`:::note` 补充上下文/提示，`:::caution` 注意事项/限制，`:::danger` 破坏性或不可逆操作，`:::tip` 有用技巧/最佳实践。
35. 35. 对以下内容保留 `[TODO: docs reviewer — ...]` 占位：截图（computer use 失败/不可用或功能未发布）、视频/GIF 嵌入、未发布功能的精确 Settings 路径、最终 URL 路径、工程师确认后仍未验证的行为。
36. 36. 若 `computer_use` 工具可用，生成草稿后尝试为 `[TODO: docs reviewer — screenshot needed]` 占位捕获截图；不可用则保留所有占位。
37. 37. 仅当以下全部为真时才尝试截图：功能已发布（不在 feature flag 后或未发布）；UI 状态能可靠程序化导航到；占位指定具体 UI surface（不是 vague 的 `show the feature working`）。跳过需要账号特定状态、特定数据或会暴露敏感信息的截图。
38. 38. 截图前设置：用 `warp-internal-computer-use` skill 以一致窗口尺寸启动 Warp；导航到相关 UI surface 或触发功能状态；等待所有动画完成且 UI 稳定；关闭无关弹窗、通知、toast；关闭无关 sidebar panels 或 panes；确认无敏感数据（tokens、API keys、私有仓库名、客户 workspace 数据、email addresses、个人信息），有则不截图。
39. 39. 截图捕获协议第一步：捕获前写出 `CAPTURE EXPECTATION`，包括 Subject、Expected elements、Expected state、Must not contain。
40. 40. 截图捕获协议：捕获后查看并验证：subject 是否可见且是清晰焦点；expected elements 是否都存在；UI 是否处于 expected state（不是过渡/加载态）；must not contain 是否未出现；文字在目标显示宽度是否可读。全过进入 quality gate；任一失败则重试一次：重新导航、等待更久、重截、重验；第二次仍失败则丢弃截图并保留 `[TODO: docs reviewer — screenshot]` 占位。
41. 41. 截图 quality gate：文字清晰；文档 UI 元素是清晰焦点；无敏感数据；UI 稳定非加载状态；匹配捕获预期；目标渲染宽度下不模糊或过大。任一失败则丢弃并保留 `[TODO: docs reviewer — screenshot]` 占位。每张截图最多尝试 2 次。
42. 42. 截图 sizing：选择最接近标准宽度——Full-width（默认）用于全窗口、宽产品表面、上下文重要的布局；~375px 用于窄 UI（popovers、command menus、side panes、dropdowns、聚焦交互流）；~300–350px 用于紧裁控件、chips、buttons、tooltips、小 menus。裁剪多余空白；同一 section 的截图序列保持同宽。
43. 43. 截图 placement：插在介绍 UI 或状态的那段之后；放在配置说明附近；放在状态或结果解释附近；视觉功能页开头可用大定向截图。不要为步骤中的每一步都加截图，只在视觉真正帮助理解时加。
44. 44. 截图 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>`。
45. 45. Alt text 规则：描述图像显示什么，不只写 `screenshot`；例如 `alt="Agent permissions settings with 'Always allow' selected for file reads"`，不要 `alt="screenshot"` 或空。
46. 46. Caption 规则：引导读者，描述展示内容而非操作；完整句，最好 ≤10 词，绝不超 ~20 词；无营销语言（避免 easily、quickly、powerful、at a glance）；不重复正文；不罗列所有可见项；sentence case，句末句号。例：`<figcaption>The Environments page in the Oz web app.</figcaption>` 可，`<figcaption>Click the toast to jump to the agent’s session.</figcaption>` 不可（程序性内容应放正文）。
47. 47. 截图文件命名：lowercase、hyphens、descriptive，如 `agent-mode-permissions-panel.png`；保存 PNG 到 `warpdotdev/docs` 的 `src/assets/<section>/`，Astro 会自动优化。
48. 48. 打开 PR 前确认 docs repo 自身要求：检查 `.agents/references/docs-worthiness-criteria.md` 的 Gate 0——feature 是否 shipped and GA、是否在 public surface；不满足则不要开 PR，告诉工程师原因并停止。剩余 gates 是判断性门槛，不应据此拒绝工程师主动要求的文档。
49. 49. 将 Step 3 确认的 content design plan 作为 PR body 的 `## Content design plan` section；优先更新已有页面，而不是新建页面。
50. 50. 提交到 `warpdotdev/docs`：clone `warpdotdev/docs` 到临时目录或使用本地 clone；把 MDX 写到 `src/content/docs/<proposed-section>/<filename>.mdx`。
51. 51. 在 `src/sidebar.ts` 对应 section 添加占位 entry，例如：`// [TODO: docs reviewer — confirm placement]` 下一行 `{ label: '<Feature name>', link: '/<section>/<feature-name>/' },`。
52. 52. 在新分支 `docs/<spec-id>-feature-draft` 上 commit 并 push。
53. 53. 写 PR body 到临时文件，再用 `--body-file` 打开 draft PR；PR body 必须包括 feature name 和 spec ID、原 spec PR 链接、草稿中所有 `[UNVERIFIED]` 和 `[TODO]` 项列表。
54. 54. 用可用方法把 body 写到 `/tmp/pr-body.md`（文件创建工具、Python `open()` 或 shell `cat` 加引号 heredoc），然后运行 `gh pr create --draft --body-file /tmp/pr-body.md ...`。
55. 55. 绝不内联传 PR body（`--body "..."`、`echo`、`printf` 直通 `gh`），因为 shell 字符串插值会展开反引号、`$vars` 和 `[ ]` glob，破坏 markdown；先写文件再传。
56. 56. PR body 的 `Docs outline` section 用普通 bullet `-` 表示 agent-verified 项，不要用 `- [x]`；`- [ ]` checkbox 只留给 `Items needing review` section，让 reviewer 明确哪些项需要行动。
57. 57. PR body 通知 spec author：找到有效 handle 时写 `/cc @<engineer-handle>`；使用 fallback 时写字面 `[TODO: tag spec author]`，不要包成 `/cc @`。请求 review from `@rachaelrenk` 和 `@hongyi-chen`。
58. 58. No-spec fallback：若 `specs/<id>/PRODUCT.md` 和 `specs/<id>/TECH.md` 不存在，先研究代码库，再采访工程师。
59. 59. No-spec research：运行 `gh search code "<feature-name>" --repo warpdotdev/warp-internal`（或按上下文用 `warp-server`）；读最相关源文件理解功能；用 `gh api repos/warpdotdev/warp-internal/contents/specs` 查不同 ID 下的 spec；用 `gh pr list --search "<feature-name>" --state merged --repo warpdotdev/warp-internal --limit 10` 看近期 merged PR。
60. 60. No-spec 研究后构建尽可能完整的图景，仅用 `ask_user_question` 问无法从代码填补的具体 gaps，不做宽泛采访；具体 framing：说明在 `app/src/ai/` 等位置找到功能、基于代码理解到的摘要、未能确定的两件事。
61. 61. 基于研究和工程师针对性回答构建 plan 和 outline，然后先走 Step 3 计划确认，再走 Step 4 大纲确认，之后才起草。
62. 62. 仅交互模式：没有 unattended mode；若没有交互 session，停止并报告此技能需要交互 session，而不是继续起草。
63. 63. 不要重新加入 unattended path：自动、release-triggered docs 用 `warpdotdev/docs` 中的 `missing_docs` skill；工程师为自己的功能要文档时，直接调用本技能，且工程师在场确认 outline 和 `TECH.md` 公开边界。
64. 64. 相关技能：`write-product-spec` 产生本技能读取的 `PRODUCT.md`；`write-tech-spec` 产生 `TECH.md`；`missing_docs`（在 `warpdotdev/docs`）是 release-triggered、worthiness-gated 的新发布功能文档管道；`scan-new-specs` 已退役。

适用边界 · 注意事项

• 没有交互 session、工程师不在场时不要用；此技能必须在确认内容设计计划、大纲和 TECH.md 公开边界后才起草，不能无人值守运行。
• 功能尚未 shipped/GA 或不在公开 surface 时不要开 docs PR；应停止并说明原因，自动发布触发文档改用 missing_docs。
• 无法安全验证 shell token/spec ID，或无法确认 TECH.md 中哪些内容可公开时不要继续；没有可确认的公开安全边界时不能起草。