draft-openspec-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Draft OpenSpec docs (scratch-plan workflow)

起草OpenSpec文档（初始计划工作流）

You are shaping a docs page with the user in the loop. The page is planned and reviewed inside the page itself, then drafted one section at a time. Load

write-openspec-docs

(the style authority) and

no-ai-slop

before drafting anything.

你将在用户参与下打造一个文档页面。页面的规划与审核将在页面内部完成，随后逐个章节进行起草。在起草任何内容之前，先加载

write-openspec-docs

（格式规范权威）和

no-ai-slop

。

1. Set up the scratch section

1. 设置草稿区域

Strip the page to its title and

goal line, then add a working section below them:

undefined

将页面精简至仅保留标题和

目标行，然后在下方添加一个工作区域：

undefined

Scratch: page plan (delete before publish)

Purpose

Structure


- **Purpose**: 3-5 dot points. Who the reader is and what they come to look up, what the page covers, what it links out to. Check `docs-lab/README.md` (the page's goal line) and `docs-lab/message-map.md` (the questions routed here) before writing it.
- **Structure**: a numbered list of the page's sections, one line each naming the section and the shape of its content (table, fence, tree, bullets).
- Say what the page will do, never what it won't. Plain words and short bullets; the user reads this in their editor.


- **目的**：3-5个要点。说明读者群体及其查询需求、页面涵盖内容、页面外链指向。撰写前请查看`docs-lab/README.md`（页面的目标行）和`docs-lab/message-map.md`（指向此页面的问题）。
- **结构**：页面章节的编号列表，每一行注明章节名称及其内容形式（表格、代码块、树形结构、项目符号）。
- 只说明页面将实现的功能，不要提及不会做的内容。使用简洁直白的语言和简短的项目符号；用户将在编辑器中阅读此内容。

2. Iterate until the plan is approved

2. 迭代直至计划获批

Plan edits are cheap; page edits aren't. Reshape the plan as many times as the user asks before drafting.
Record every decision in the plan itself, not only in chat. Add a
```
### Notes
```
list for follow-ups that belong to other pages and product observations found along the way.
The user may edit the file directly between turns; their edits are decisions, not drift to revert.
Surface one open call at a time, with a recommendation.

调整计划的成本很低，但修改页面的成本很高。在起草前，根据用户要求多次调整计划。
所有决策都要记录在计划本身中，而不仅仅是在聊天里。添加
```
### Notes
```
列表，记录属于其他页面的后续任务以及过程中发现的产品观察结果。
用户可能会在回合之间直接编辑文件；他们的编辑即为决策，无需回退。
每次只提出一个待处理请求，并给出建议。

3. Add the draft plan, then draft step by step

3. 添加草稿计划，然后逐步起草

Once the structure holds, add a

### Draft plan

below the notes: one step per page section, each with an ID and a readable title (

**D1. Goal line and intro**

), ending with a consolidation step (cross-page updates) and a cleanup step. Then:

Wait for the user to call a step ID. Draft exactly that step, into the page above the scratch block.
Verify each fact against source before writing it; a cheap grep beats trust. Reference content shows the raw contract (templates, instructions, config) verbatim in fences, linked to the file on GitHub, rather than paraphrasing it.
Keep sibling sections on a repeatable sub-structure so the page scans as one system.
Mark the step
```
(done)
```
in the plan, report what landed, and name the next step.

确定结构后，在笔记下方添加

### Draft plan

：每个页面章节对应一个步骤，每个步骤包含ID和易读标题（例如

**D1. 目标行与引言**

），最后包含一个整合步骤（跨页面更新）和一个清理步骤。然后：

等待用户调用步骤ID。仅起草该步骤，并将内容添加到草稿区块上方的页面中。
撰写前请根据来源验证每个事实；简单的grep搜索比盲目信任更可靠。参考内容需将原始约定（模板、说明、配置）以代码块形式原样呈现，并链接到GitHub上的对应文件，而非转述。
保持同级章节采用一致的子结构，使页面整体看起来统一。
在计划中标记该步骤为
```
(done)
```
，报告已完成的内容，并指明下一步骤。

4. Consolidation and cleanup

4. 整合与清理

Consolidation: update everything that points at the page. The README goal line (verbatim match with the page's
```
>
```
line), the message map, the sync config (
```
website/docs.sync.config.mjs
```
), and any cross-links found by grepping the tree. Run
```
node website/scripts/sync-docs.mjs
```
to validate.
Cleanup: delete the scratch block, run the retrievability and glance tests from
```
write-openspec-docs
```
at desktop and narrow widths, and flip the page's message-map row to Answered if its prose landed.

整合：更新所有指向该页面的内容。包括README目标行（与页面的
```
>
```
行完全匹配）、消息映射、同步配置文件(
```
website/docs.sync.config.mjs
```
)，以及通过搜索目录树找到的所有交叉链接。运行
```
node website/scripts/sync-docs.mjs
```
进行验证。
清理：删除草稿区块，在桌面端和窄屏模式下运行
```
write-openspec-docs
```
中的可检索性和概览测试，若页面文案已确定，则将消息映射中该行标记为“已答复”。