spec-writer

name	spec-writer
description	genesis Step 2：将模糊或高层需求转化为严格的产品需求文档（PRD）；含 craft 脚手架、PRD spec 契约、可选子代理分片编排与 Step 完成信号。适用于需求含糊、范围过大或表达停留在概念层的场景。

需求侦探手册

“软件开发最难的部分，不是如何实现，而是精确定义到底要实现什么。”

你的任务是消灭歧义。

genesis Step 2（范围与衔接）

本模板相对 templates/.agents/skills/spec-writer 增加 craft 脚手架、spec 契约（落盘语义）、子代理编排与 completion；下列「执行清单 / 方法论 / 10 维歧义扫描表 / User Story 质量闸门表」的规范性效力不变——追问苏格拉底行为、一次性一个问题、[NEEDS CLARIFICATION] 硬上限、Non-Goals 与 User Story 闸门等规则** verbatim 适用**。

craft scaffolding（产物脚手架）

在执行清单第 4 步（落盘 01_PRD.md）前，骨架必须先就位；填内容时不得删模板中的规范性章节，无信息则写 [NOT APPLICABLE | reason] 或 [ASSUMPTION]，不得留白假装完成。

工件	路径	必须满足
版本目录	.anws/v{N}/	v{N} 与宿主 genesis / 会话约定一致；首轮创建或显式沿用既有 v{N}，禁止 silent fork。
PRD	.anws/v{N}/01_PRD.md	唯一权威 Step 2 产出；内容由 references/prd_template.md 驱动；禁止仅以聊天长篇代替落盘。
模板	references/prd_template.md	起草 PRD 前全文读取；标题层级与必选段落以模板为准，额外附录允许但不可替代模板必选节。

就绪检查（内部，可向用户简述）：已选 v{N}；已读本 SKILL + prd_template.md；已枚举至少 3 条 User Story 草稿与 ≥3 Non-Goals 再进入落盘段落扩展。

spec 契约（PRD 落盘语义）

[!IMPORTANT] PRD 段落在合并进 genesis 链路时视作可对下游断言的契约草稿（架构、任务分解、challenge），须同时满足：

• 可验证：凡写入「必须 / 禁止 / SLA / 用户数 / 兼容性」类陈述，须有 Given-When-Then、指标或枚举；否则不得标为已实现需求，只可 [ASSUMPTION] 或删至 Non-Goals。
• 可定位：每条 User Story 带 [REQ-XXX]；术语与系统在 PRD 内与下文「涉及系统」引用自洽（下游以 02_ARCHITECTURE_OVERVIEW.md 对齐时不得无故改名）。
• 可收敛歧义：[NEEDS CLARIFICATION] ≤ 3（硬限制）；超限则默认值 + [ASSUMPTION: …]；禁止对已声明的通用默认（见原文 10 维扫描节）再行追问刷数。
• 可追溯价值：每条需求能一句话对齐用户价值；Non-Goals 与 Goals 互斥且无空洞「也许不做」。
• 一致性：同一事实在摘要与详情中不二次矛盾表述；修正采用原子段落替换，不留互相打架的并排说法。

Challenge / 下游专用对齐：若在报告或附件中摘录 PRD 结论，摘录须带 小节锚点 或 01_PRD.md Stable 标题，禁止只写「见 PRD」。

子代理编排（可选）

当宿主支持并行子会话时：

角色	职责
父代理	选定 v{N}、加载用户意图与上下文、合并本子代理返回的结构化块、去重与同主题择优、对 .anws/v{N}/01_PRD.md 保持 单写者、跑完强制「10 维歧义扫描」与 User Story 质量闸门并最终交付用户确认。
子代理	只吃有界切片：例如「仅生成澄清问题批次（附推荐答）」「仅提取 / 重写 User Stories（仍为草稿）」「仅对 10 维表中第 k 维做 Clear/Partial/Missing 标注 + 补丁建议」「仅将感觉词改写为度量候选列表」；返回 Markdown 结构化块 + 锚点建议；不假设已读父代理专有上下文。

单写者：任一 01_PRD.md 在同一轮 genesis Step 2 仅一个 writer；子代理不得在父未授权下直接写该路径。

交接清单（子 → 父）

• 声明交付物类型（问题列表 / Story 草稿 / 扫描向量 / 感觉词度量表）及 不适用 的维度（附一行原因）。
• 所有条目可映射到 PRD 将使用的 小节标题或 [REQ-XXX] 占位，无锚点则标「待父挂载」。
• 不引入与父已声明 Non-Goals 冲突的新需求；若冲突可能，单列「须父裁定」。
• 子代理停于结构化块移交；后续编辑由父合并入库。

completion（genesis Step 2 完成信号）

Step 2 不得宣称完成，除非同时满足：

门禁	条件
落盘	.anws/v{N}/01_PRD.md 存在且可被独立打开；结构与 prd_template.md 必选节对齐。
内容	含 User Stories（过质量闸门）、验收标准、≥3 Non-Goals；每条需求可测试、可度量或可显式假定。
歧义	「10 维歧义扫描」已执行完毕；所有 Partial / Missing 已修复、[ASSUMPTION] 化或在硬限制规则下收口。
标签	[NEEDS CLARIFICATION] ≤ 3；Story 均无未量化感觉词或通过改写 / 假定关闭。
人	用户已对 PRD 确认（或明确书面弃权并记录为 [ASSUMPTION: stakeholder sign-off deferred]）；不得伪称已确认。
Handoff	父代理已向用户交付短摘要表（目标 / 关键 REQ 数 / 开放澄清数 / Non-Goals 数 / 下一 Step 推荐阅读顺序）。

未达到上表任一 硬 行 → Step 2 状态为 blocked / in_progress，不得在链路中静默进入架构起草。

---

执行清单（唯一权威顺序）

与上文 「craft scaffolding」、「completion（genesis Step 2 完成信号）」 表对齐；最终放行以 completion 表硬行为准，本清单只定义操作顺序（合并原「快速开始 / 强制步骤 / 完成检查」，避免重复阅读）。

1. 阅读需求：识别「感觉词」与隐含边界（强制）。
2. 深度思考：3–7 轮结构化推理（按复杂度）；产出 User Story 草稿、歧义点、澄清问题（强制）。
3. 追问澄清：未获答复不得推进主线（强制）。
4. 落盘前下限：≥3 User Story、≥3 Non-Goal、澄清感觉词；读取 references/prd_template.md，创建 .anws/v{N}/01_PRD.md，禁止仅以聊天代替落盘（强制）。
5. 落盘后：执行下文「10 维歧义扫描」并收口 Partial / Missing；跑 User Story 质量闸门；[NEEDS CLARIFICATION] ≤3（强制）。
6. 收口：满足 completion 表全部硬行 + 用户确认 PRD（或已记录的弃权假定）。

方法工具

1. 苏格拉底追问

• 用户：“我希望它很快。”
• 你：“是指 p99 小于 100ms？还是只要求 UI 采用乐观更新？”
• 目标：把形容词转成数字和可验证标准。

2. 上下文压缩

• 输入：500 行聊天记录。
• 动作：提取 User Stories，即 “As a User, I want X, so that Y.”
• 丢弃：过早出现的实现细节（例如“使用 Redis”）。

3. Non-Goal 设定（画圈）

• 明确定义我们不做什么。
• 为什么：防止范围蔓延，避免后续不断冒出“那 X 呢？”的问题。

侦探守则

1. 契约优先：如果无法验证，就不要写进 PRD。
2. 不抢设计工作：描述 做什么，不要过早写 怎么做。实现方式留给架构设计阶段。
3. 用户价值优先：每条需求都必须能追溯到明确的用户价值。

工具箱

• references/prd_template.md：产品需求文档模板。

10 维歧义扫描

起草 PRD 后，你必须从以下 10 个维度系统性扫描全文。这一步是为了用可重复、可穷尽的方法替代随意的“还有问题吗？”。

对每个维度，标记状态：Clear / Partial / Missing

#	维度	检查内容	状态
1	功能范围与行为	核心目标 / 成功标准 / 明确排除项 / 用户角色区分
2	领域与数据模型	实体、属性、关系 / 唯一性规则 / 生命周期与状态转换 / 数据规模假设
3	交互与 UX 流程	关键用户路径 / 错误、空状态、加载状态 / 无障碍与 i18n
4	非功能质量	性能 / 可扩展性 / 可靠性 / 可观测性 / 安全与隐私 / 合规
5	集成与外部依赖	外部服务失败模式 / 导入导出格式 / 协议版本假设
6	边界情况与失败场景	负向场景 / 限流 / 并发冲突处理
7	约束与权衡	技术约束 / 显式权衡记录 / 被否决的备选架构
8	术语一致性	标准术语表 / 同义词在全文中的统一
9	完成信号	验收标准是否可测 / DoD 是否可量化
10	占位符与模糊词	TODO 标记 / 未量化形容词（快、可扩展、安全、直观、健壮）

规则：

• 对于 Partial 或 Missing 项，按 影响 × 不确定性 排序，选取前 5 个向用户追问
• 一次只问一个问题；给出推荐答案；用户可接受或自定义
• 用户回答后，原子化写入对应 PRD 段落，不允许保留互相矛盾的文本
• [NEEDS CLARIFICATION] 标签数量硬限制 ≤ 3；若仍超出，则采用合理默认值并加 [ASSUMPTION: ...]
• 不要向用户追问这些合理默认值：行业通用的数据保留策略、标准 Web/移动性能预期、带兜底的友好错误提示、标准 Session 或 OAuth2 认证

User Story 质量闸门

PRD 中的每条 User Story，在 PRD 被视为完成前，都必须通过以下检查：

检查项	要求
唯一 ID	必须带 [REQ-XXX] 以便追踪
优先级	标记为 P0 / P1 / P2，且 P0 必须排前
独立可测	说明该故事如何独立演示和验证
涉及系统	列出具体系统 ID（必须与 02_ARCHITECTURE_OVERVIEW.md 对齐）
验收标准	至少 1 条 Given-When-Then + 至少 1 个错误场景
边界情况	至少识别 1 个边界条件
无模糊感觉词	不允许出现未量化形容词（如快 → <100ms p99，可扩展 → 支持 N 用户）
用户价值	用一句话描述对终端用户的价值

若任一 User Story 未通过检查，必须先修复，再交付 PRD。