scan-new-specs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

scan-new-specs

扫描新规格文档（scan-new-specs）

Scan

warpdotdev/warp

and

warp-server

for recently merged product or tech specs that lack a corresponding docs draft. For each gap:

If the spec is complete — automatically run
```
write-feature-docs
```
in ambient mode to generate a full draft PR in
```
warpdotdev/docs
```
, then ping the engineer to review it
If the spec is thin — ping the engineer directly to either flesh out the spec or kick off the docs workflow manually

In both cases, post a summary to

#growth-docs

TODO for reviewers:
#growth-docs
is a temporary channel for engineer pings. Identify a more appropriate eng-facing channel (e.g. a shared eng/docs channel,
#dev
, or a dedicated
#docs-requests
channel) once this workflow is established.

扫描

warpdotdev/warp

和

warp-server

仓库中近期合并的产品或技术规格文档，检查是否缺少对应的文档草稿。针对每个缺口：

若规格文档完整 —— 在ambient模式下自动运行
```
write-feature-docs
```
，在
```
warpdotdev/docs
```
仓库中生成完整的草稿PR，然后通知工程师进行评审
若规格文档内容单薄 —— 直接通知工程师，要求其补充规格文档内容或手动启动文档工作流

无论哪种情况，都需在

#growth-docs

频道发布总结内容。

评审者待办事项：
#growth-docs
是用于通知工程师的临时频道。待此工作流建立后，请确定一个更合适的面向工程师的频道（例如共享的工程/文档频道、
#dev
或专用的
#docs-requests
频道）。

Configuration

配置

Before running, confirm these values (or accept the defaults):

Setting	Default	Description
`LOOKBACK_DAYS`	`3`	How many days back to scan for merged spec PRs
`SLACK_CHANNEL`	`#growth-docs`	Slack channel for engineer pings and summaries (temporary — see TODO above)
`SLACK_BOT_TOKEN`	From `buzz` environment	Slack bot token for posting via API (already available in the `buzz` Oz environment)

This skill uses the Slack API (

chat.postMessage

) rather than an incoming webhook, which enables real user pings. The

buzz

Oz environment already has the required

SLACK_BOT_TOKEN

. No new secrets setup is needed.

SLACK_BOT_TOKEN

is not set, print all messages to stdout instead.

运行前，请确认以下配置值（或使用默认值）：

设置项	默认值	描述
`LOOKBACK_DAYS`	`3`	扫描近期合并的规格PR的回溯天数
`SLACK_CHANNEL`	`#growth-docs`	用于通知工程师和发布总结的Slack频道（临时频道 —— 参见上述待办事项）
`SLACK_BOT_TOKEN`	来自 `buzz` 环境	用于通过API发布消息的Slack机器人令牌（ `buzz` Oz环境中已提供）

本技能使用Slack API（

chat.postMessage

）而非传入webhook，支持真实的用户@提及。

buzz

Oz环境已提供所需的

SLACK_BOT_TOKEN

，无需配置新的密钥。

若未设置

SLACK_BOT_TOKEN

，则将所有消息打印至标准输出。

Step 1: Find recently merged specs

步骤1：查找近期合并的规格文档

List merged PRs from both repos since the lookback date, then filter by changed files. Do not use

--search "in:files"

(GitHub does not support file-path filtering in PR search) and use a portable date command that works on both Linux and macOS:

bash

undefined

列出回溯日期以来两个仓库中合并的PR，然后按变更文件进行筛选。请勿使用

--search "in:files"

（GitHub不支持在PR搜索中进行文件路径筛选），请使用可在Linux和macOS上运行的跨平台日期命令：

bash

undefined

Portable date calculation (GNU/Linux and BSD/macOS compatible)

可移植的日期计算（兼容GNU/Linux和BSD/macOS）

SINCE=$(date -d "-${LOOKBACK_DAYS} days" +%Y-%m-%d 2>/dev/null
|| date -v-${LOOKBACK_DAYS}d +%Y-%m-%d)

List all recently merged PRs (no file-path filter -- we check files next)

列出所有近期合并的PR（暂不进行文件路径筛选，后续步骤检查文件）

gh pr list
--repo warpdotdev/warp
--state merged
--search "merged:>${SINCE}"
--json number,title,author,mergedAt,url
--limit 100

Repeat for warp-server

针对warp-server仓库重复执行上述命令

gh pr list
--repo warpdotdev/warp-server
--state merged
--search "merged:>${SINCE}"
--json number,title,author,mergedAt,url
--limit 100


For each PR returned, check whether it actually contains a new `specs/*/PRODUCT.md` by inspecting the changed files (this is the correct filter step):

```bash
gh pr view <number> --repo warpdotdev/<repo> --json files -q '.files[].path' \
  | grep -E '^specs/.+/PRODUCT\.md$'

Collect the list of: spec ID (the directory name under

specs/

), spec PR number and URL, PR author GitHub username, repo (

warp

warp-server

), and merge date.

For each PR author's GitHub username, resolve their Slack identity:

bash

undefined

gh pr list
--repo warpdotdev/warp-server
--state merged
--search "merged:>${SINCE}"
--json number,title,author,mergedAt,url
--limit 100


对于返回的每个PR，通过检查变更文件确认是否包含新的 `specs/*/PRODUCT.md`（这是正确的筛选步骤）：

```bash
gh pr view <number> --repo warpdotdev/<repo> --json files -q '.files[].path' \
  | grep -E '^specs/.+/PRODUCT\.md$'

收集以下信息：规格ID（

specs/

下的目录名称）、规格PR编号和URL、PR作者的GitHub用户名、仓库（

warp

或

warp-server

）以及合并日期。

针对每个PR作者的GitHub用户名，解析其Slack身份：

bash

undefined

Get the engineer's name and email from GitHub

从GitHub获取工程师的姓名和邮箱

ENG_NAME=$(gh api users/<github-username> -q '.name // .login') ENG_EMAIL=$(gh api users/<github-username> -q '.email // empty')

Look up their Slack user ID by email (real ping, not just a name mention)

通过邮箱查找其Slack用户ID（真实@提及，而非仅名称提及）

if [ -n "$ENG_EMAIL" ]; then SLACK_USER_ID=$(curl -s -H "Authorization: Bearer $SLACK_BOT_TOKEN"
"https://slack.com/api/users.lookupByEmail?email=${ENG_EMAIL}"
| python3 -c "import sys,json; d=json.load(sys.stdin); print(d['user']['id'] if d.get('ok') else '')") fi

Use <@USER_ID> for a real ping if lookup succeeded; fall back to @name if not

若查找成功，则使用 <@USER_ID> 进行真实@提及；否则回退为 @name，并添加手动验证提示

if [ -n "$SLACK_USER_ID" ]; then ENG_MENTION="<@${SLACK_USER_ID}>" else ENG_MENTION="@${ENG_NAME} (Slack ID not found — verify this is the right person)" fi


Store `ENG_MENTION`, `ENG_NAME`, and `ENG_GITHUB` for use in Slack messages.

if [ -n "$SLACK_USER_ID" ]; then ENG_MENTION="<@${SLACK_USER_ID}>" else ENG_MENTION="@${ENG_NAME} (未找到Slack ID —— 请确认是否为正确人员)" fi


存储 `ENG_MENTION`、`ENG_NAME` 和 `ENG_GITHUB`，用于Slack消息中。

Step 2: Check for existing docs coverage

步骤2：检查现有文档覆盖情况

For each spec found, check

warpdotdev/docs

for an open/draft or merged PR that mentions the spec ID. Run two separate queries to avoid counting closed-unmerged PRs as coverage:

bash

undefined

针对每个找到的规格文档，检查

warpdotdev/docs

仓库中是否存在提及该规格ID的开放/草稿或已合并PR。执行两个独立查询，避免将已关闭未合并的PR视为已覆盖：

bash

undefined

Check for open or draft PRs

检查开放或草稿PR

gh pr list
--repo warpdotdev/docs
--state open
--search "<spec-id>"
--json number,title,state,url
--limit 5

Check for merged PRs

检查已合并PR

gh pr list
--repo warpdotdev/docs
--state merged
--search "<spec-id>"
--json number,title,state,url
--limit 5


A spec is considered **covered** if either query returns results (open, draft, or merged PR exists). Skip covered specs.

A spec is **uncovered** if neither query returns results. Closed-unmerged PRs do **not** count as coverage — a closed PR signals abandoned work that needs re-triggering.

gh pr list
--repo warpdotdev/docs
--state merged
--search "<spec-id>"
--json number,title,state,url
--limit 5


若任一查询返回结果（存在开放、草稿或已合并PR），则该规格文档被视为**已覆盖**，跳过此类规格文档。

若两个查询均无结果，则该规格文档被视为**未覆盖**。已关闭未合并的PR不视为已覆盖——关闭的PR意味着文档工作已中止，需要重新触发。

Step 3: Assess spec completeness

步骤3：评估规格文档完整性

For each uncovered spec, read

specs/<id>/PRODUCT.md

and assess whether it has enough content to auto-draft from:

Complete (proceed to auto-draft) if ALL of the following are true:

File is at least 40 lines long
Contains a
```
## Behavior
```
section (or equivalent) with numbered invariants or user-facing steps
Describes at least one concrete user action (not just a summary paragraph)

Thin (ping engineer instead) if the spec is a stub — only a Summary section, fewer than 40 lines, or no behavior detail.

针对每个未覆盖的规格文档，读取

specs/<id>/PRODUCT.md

，评估其是否有足够内容用于自动生成草稿：

完整（可自动生成草稿）需同时满足以下所有条件：

文件长度至少为40行
包含
```
## Behavior
```
章节（或等效章节），其中包含编号的约束条件或面向用户的步骤
描述至少一个具体的用户操作（而非仅摘要段落）

内容单薄（需通知工程师）指规格文档为 stub 形式——仅包含摘要章节、长度不足40行，或无行为细节。

Step 4: Act based on spec completeness

步骤4：根据规格文档完整性执行操作

Path A: Complete spec → auto-draft

路径A：完整规格文档 → 自动生成草稿

Run
```
write-feature-docs
```
in ambient mode (see
```
write-feature-docs
```
skill for details) — this skips the interactive outline confirmation and instead embeds the outline as a checklist in the PR description
The PR is opened in
```
warpdotdev/docs
```
with the draft and a checklist of items needing engineer verification

Request review from the engineer (

@<github-username>

) and from

@rachaelrenk

@petradonka

, and

@hongyi-chen

Post this Slack message to
```
SLACK_CHANNEL
```
:

📄 *Docs draft auto-generated*

Feature: *<spec-id>* (from `<repo>`)
Spec PR: <spec-pr-url>
<@USER_ID> (GitHub: <github-username>)

I’ve opened a draft docs PR for review: <docs-pr-url>
Please check the items marked *[UNVERIFIED]* and *[TODO]* in the PR — those are the only things that need your input.

在ambient模式下运行
```
write-feature-docs
```
（详见
```
write-feature-docs
```
技能）——此模式会跳过交互式大纲确认，而是将大纲作为检查清单嵌入PR描述中
在
```
warpdotdev/docs
```
仓库中创建包含草稿和工程师需验证事项检查清单的PR

请求工程师（

@<github-username>

）以及

@rachaelrenk

、

@petradonka

和

@hongyi-chen

进行评审

在
```
SLACK_CHANNEL
```
发布以下Slack消息：

📄 *文档草稿已自动生成*

功能：*<spec-id>*（来自 `<repo>`）
规格PR：<spec-pr-url>
<@USER_ID>（GitHub：<github-username>）

我已创建一份文档草稿PR供评审：<docs-pr-url>
请检查PR中标记为 *[UNVERIFIED]* 和 *[TODO]* 的事项——这些是仅需您参与的内容。

Path B: Thin spec → ping engineer

路径B：内容单薄的规格文档 → 通知工程师

Post this Slack message to

SLACK_CHANNEL

📋 *New spec needs docs — not enough detail to auto-draft*

Feature: *<spec-id>* (from `<repo>`)
Spec PR: <spec-pr-url>
<@USER_ID> (GitHub: <github-username>)

The spec doesn’t have enough behavior detail for me to auto-generate docs yet. Please either:
• Add more detail to `specs/<spec-id>/PRODUCT.md` (a Behavior section with user-facing steps), OR
• Ping the docs team in this channel and we’ll draft it manually

If there are no uncovered specs, post:

✅ *Docs coverage scan complete* — all recently merged specs have docs coverage.

在

SLACK_CHANNEL

发布以下Slack消息：

📋 *新规格文档需要配套文档——内容不足无法自动生成草稿*

功能：*<spec-id>*（来自 `<repo>`）
规格PR：<spec-pr-url>
<@USER_ID>（GitHub：<github-username>）

该规格文档的行为细节不足，无法自动生成文档。请您选择以下操作之一：
• 为 `specs/<spec-id>/PRODUCT.md` 添加更多细节（包含面向用户步骤的Behavior章节），或
• 在本频道@文档团队，我们将手动生成文档

若未发现未覆盖的规格文档，则发布：

✅ *文档覆盖范围扫描完成* —— 所有近期合并的规格文档均已覆盖。

Step 5: Post to Slack

步骤5：发布至Slack

Post each message using the Slack API. Build the JSON payload with

jq

to safely handle newlines, quotes, and backslashes in

$MESSAGE

bash

jq -n \
  --arg channel "$SLACK_CHANNEL" \
  --arg text "$MESSAGE" \
  '{channel: $channel, text: $text}' \
| curl -s -X POST https://slack.com/api/chat.postMessage \
    -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
    -H 'Content-type: application/json' \
    -d @-

SLACK_BOT_TOKEN

is not set, print the message to stdout instead.

使用Slack API发布每条消息。使用

jq

构建JSON负载，以安全处理

$MESSAGE

中的换行符、引号和反斜杠：

bash

jq -n \
  --arg channel "$SLACK_CHANNEL" \
  --arg text "$MESSAGE" \
  '{channel: $channel, text: $text}' \
| curl -s -X POST https://slack.com/api/chat.postMessage \
    -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
    -H 'Content-type: application/json' \
    -d @-

若未设置

SLACK_BOT_TOKEN

，则将消息打印至标准输出。

Step 6: Print a summary

步骤6：打印总结

Always print a run summary to stdout:

scan-new-specs run summary
  Repos scanned:         warpdotdev/warp, warp-server
  Lookback window:       <N> days (since <date>)
  Specs found:           <N>
  Already covered:       <N>
  Auto-drafted:          <N>   (complete spec → draft PR opened)
  Pinged (thin spec):    <N>   (incomplete spec → engineer notified)
  Slack channel:         <channel>

始终将运行总结打印至标准输出：

scan-new-specs 运行总结
  扫描的仓库：         warpdotdev/warp, warp-server
  回溯窗口：           <N> 天（自 <date> 起）
  找到的规格文档：     <N>
  已覆盖的规格文档：   <N>
  自动生成草稿的数量： <N>  （完整规格文档 → 已创建草稿PR）
  已通知的单薄规格：   <N>  （不完整规格文档 → 已通知工程师）
  Slack频道：         <channel>

Scheduling

调度

This skill is designed to run as a scheduled Oz ambient agent every 2–3 days. A suggested prompt for the Oz agent configuration:

"Run scan-new-specs to check warpdotdev/warp and warp-server for newly merged PRODUCT.md specs that don't have a corresponding docs PR in warpdotdev/docs. For complete specs, auto-generate a draft docs PR and tag the engineer. For thin specs, ping the engineer in Slack. Post a summary to #growth-docs. Use the last 3 days as the lookback window."

Suggested schedule: every Monday, Wednesday, and Friday at 9am PT — frequent enough to catch specs quickly, but not noisy.

本技能设计为定时运行的Oz ambient agent，每2-3天运行一次。Oz agent配置的建议提示语：

"运行scan-new-specs，检查warpdotdev/warp和warp-server仓库中新合并的PRODUCT.md规格文档是否在warpdotdev/docs仓库中有对应的文档PR。对于完整的规格文档，自动生成文档草稿PR并标记工程师；对于内容单薄的规格文档，在Slack中通知工程师。将总结发布至#growth-docs频道。使用过去3天作为回溯窗口。"

建议调度计划：每周一、周三、周五太平洋时间上午9点运行——频率足够及时发现规格文档，且不会过于频繁造成干扰。

Deduplication note

去重说明

This skill does not maintain persistent state between runs. Deduplication relies entirely on whether a docs PR exists in

warpdotdev/docs

— if a PR is open or merged for a spec, it won't be flagged again. This means a spec will continue to generate nudges until someone opens a docs PR for it (even a draft).

Edge case: if a docs draft PR was opened and then closed (not merged), the spec will be re-flagged on the next run since closed PRs are not counted as coverage. This is intentional — a closed PR means docs work was abandoned and needs re-triggering.

本技能在运行之间不维护持久化状态。去重完全依赖

warpdotdev/docs

仓库中是否存在文档PR——若某规格文档存在开放或已合并的PR，则不会再次标记。这意味着，直到有人为该规格文档创建文档PR（即使是草稿），否则会持续收到提醒。

边缘情况：若文档草稿PR已创建但随后被关闭（未合并），则在下一次运行时该规格文档会被重新标记，因为关闭的PR不视为已覆盖。此设计是有意为之——关闭的PR意味着文档工作已中止，需要重新触发。

Slack mention note

Slack提及说明

This skill uses the Slack API (

chat.postMessage

) with the

SLACK_BOT_TOKEN

from the

buzz

Oz environment. This supports real

<@USER_ID>

mentions — engineers will receive a direct notification when their spec is detected.

The user ID is resolved by looking up the engineer's GitHub email against the Slack

users.lookupByEmail

API. If the engineer has a private GitHub email, the lookup will fail and the message will fall back to a plain-text name with a note to verify manually.

本技能使用

buzz

Oz环境中的

SLACK_BOT_TOKEN

通过Slack API（

chat.postMessage

）发送消息。支持真实的

<@USER_ID>

提及——工程师在其规格文档被检测到时会收到直接通知。

用户ID通过将工程师的GitHub邮箱与Slack

users.lookupByEmail

API进行匹配解析。若工程师的GitHub邮箱为私有，则查找会失败，消息将回退为纯文本名称，并添加手动验证提示。

scan-new-specs

Original

Translation

scan-new-specs

扫描新规格文档（scan-new-specs）

Configuration

配置

Step 1: Find recently merged specs

步骤1：查找近期合并的规格文档

Portable date calculation (GNU/Linux and BSD/macOS compatible)

可移植的日期计算（兼容GNU/Linux和BSD/macOS）

List all recently merged PRs (no file-path filter -- we check files next)

列出所有近期合并的PR（暂不进行文件路径筛选，后续步骤检查文件）

Repeat for warp-server

针对warp-server仓库重复执行上述命令

Get the engineer's name and email from GitHub

从GitHub获取工程师的姓名和邮箱

Look up their Slack user ID by email (real ping, not just a name mention)

通过邮箱查找其Slack用户ID（真实@提及，而非仅名称提及）

Use <@USER_ID> for a real ping if lookup succeeded; fall back to @name if not

若查找成功，则使用 <@USER_ID> 进行真实@提及；否则回退为 @name，并添加手动验证提示

Step 2: Check for existing docs coverage

步骤2：检查现有文档覆盖情况

Check for open or draft PRs

检查开放或草稿PR

Check for merged PRs

检查已合并PR

Step 3: Assess spec completeness

步骤3：评估规格文档完整性

Step 4: Act based on spec completeness

步骤4：根据规格文档完整性执行操作

Path A: Complete spec → auto-draft

路径A：完整规格文档 → 自动生成草稿

Path B: Thin spec → ping engineer

路径B：内容单薄的规格文档 → 通知工程师

Step 5: Post to Slack

步骤5：发布至Slack

Step 6: Print a summary

步骤6：打印总结

Scheduling

调度

Deduplication note

去重说明

Slack mention note

Slack提及说明

Related skills

相关技能