| 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；子代理不得在父未授权下直接写该路径。
交接清单（子 → 父）
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 表硬行为准，本清单只定义操作顺序（合并原「快速开始 / 强制步骤 / 完成检查」，避免重复阅读）。
- 阅读需求：识别「感觉词」与隐含边界（强制）。
- 深度思考：3–7 轮结构化推理（按复杂度）；产出 User Story 草稿、歧义点、澄清问题（强制）。
- 追问澄清：未获答复不得推进主线（强制）。
- 落盘前下限：≥3 User Story、≥3 Non-Goal、澄清感觉词；读取
references/prd_template.md，创建 .anws/v{N}/01_PRD.md，禁止仅以聊天代替落盘（强制）。
- 落盘后：执行下文「10 维歧义扫描」并收口
Partial / Missing；跑 User Story 质量闸门；[NEEDS CLARIFICATION] ≤3（强制）。
- 收口：满足 completion 表全部硬行 + 用户确认 PRD（或已记录的弃权假定）。
方法工具
1. 苏格拉底追问
- 用户：“我希望它很快。”
- 你：“是指 p99 小于 100ms？还是只要求 UI 采用乐观更新？”
- 目标：把形容词转成数字和可验证标准。
2. 上下文压缩
- 输入：500 行聊天记录。
- 动作：提取 User Stories，即 “As a User, I want X, so that Y.”
- 丢弃：过早出现的实现细节（例如“使用 Redis”）。
3. Non-Goal 设定（画圈）
- 明确定义我们不做什么。
- 为什么：防止范围蔓延，避免后续不断冒出“那 X 呢？”的问题。
侦探守则
- 契约优先：如果无法验证，就不要写进 PRD。
- 不抢设计工作：描述 做什么，不要过早写 怎么做。实现方式留给架构设计阶段。
- 用户价值优先：每条需求都必须能追溯到明确的用户价值。
工具箱
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。
