timzaak/web-dev-skills/t-prd

PRD 草稿维护

运行时边界：${CLAUDE_PLUGIN_ROOT}/protocols/runtime-boundaries.md（判断产物写入位置或项目事实与插件默认冲突时读） 决策依据、提问与 PRD 澄清门禁：${CLAUDE_PLUGIN_ROOT}/protocols/decision-continuity-contract.md（收集信息时读，提问或写入前必读）

若本 skill、spec 或既有文档之间冲突，停止、说明冲突并等待澄清；不要平均折中。

目标

优先基于同一 feature 的 Decision Brief、Decision Log 和技术预研报告，结合用户补充信息创建或更新 PRD 草稿；已有相关 PRD 必须查阅，用于确定业务基线和本次变更关系。先补齐必要的 draft user story，再创建或更新一份 PRD 草稿，供人类快速审阅。.ai/prd 和 .ai/user-stories 是实现前和实现期间的临时候选需求工作区，不是长期权威源。

输出文件：

• .ai/prd/<domain>/[feature].md — PRD 草稿，至少包含：相关用户故事引用、范围界定、需求概述、业务规则与状态、功能需求与验收目标、API 相关约束 / 前端交互约束（各标明适用或不适用）、已确认决策及 Decision ID、参考资料
• .ai/user-stories/<domain>/[feature].md — draft user story，按需新增或补齐
• .ai/decision-log/[feature].md — 存在，或产生用户决策、问题状态变化或重要 AI 决策时创建或更新

参数要求

• [feature] 必须是 feature 名称；文件名仅允许英文、数字、空格、下划线、连字符
• 缺失或非法时终止并提示参数格式

核心约束

路径与域：

• <domain> 只能是 auth、billing、core、integration；父目录缺失且目标域已明确时才创建对应 .ai/ 子目录
• /t-prd 不写入 docs/prd/ 和 docs/user-stories/
• PRD、用户故事和技术预研的读取与写入边界统一参考 ${CLAUDE_PLUGIN_ROOT}/protocols/requirement-source-contract.md

PRD 内容边界：

• 聚焦产品边界与规则，不承载接口 schema、数据库建表或技术方案
• 可以写：接口能力范围、访问控制原则、租户/realm 边界、兼容性要求、前端页面入口、关键交互、状态反馈约束、skill 交付能力范围（触发场景、能力边界、成功条件；不写文件结构）
• 禁止写：具体端点（GET/POST /api/...）、请求/响应参数表、HTTP 状态码列表、数据库表结构/迁移方案、Rust/TypeScript 类型定义

更新行为：

• 已有同名草稿 → update 路径，以草稿为基底逐章更新
• 无草稿但有同名正式 PRD → draft-from-published 路径，以正式 PRD 为基线创建草稿，不覆盖正式 PRD
• 无草稿且无正式 PRD → create 路径，使用 template.md
• 已有同名 draft user story 文件 → 追加到合适章节，不重建

user story 引用：

• PRD 只引用相关用户故事（ID、标题、优先级、来源文件），不复制完整验收文本
• 已发布 user story 足够覆盖时，PRD 可直接引用 docs/user-stories/...
• 缺少或需要补齐的本轮用户故事写入 .ai/user-stories/<domain>/<feature>.md；draft user story 可以按角色分组组织在同一 feature 文件中

提问与澄清门禁

写入前必须通过决策连续性协议的 PRD Clarification Gate；可合理推断不等于已确认。

Input Contract

本轮上游输入（先按 feature 精确查找；存在时必须读取）：

• .ai/decision/[feature].md — 产品立项决策简报（必须检查；存在时必须读取，来自 /t-decision）
• .ai/decision-log/[feature].md — 跨阶段决策账本（存在时必须读取）
• .ai/tech-research/[feature].md — 技术可行性研究报告（必须检查；存在时必须读取，来自 /t-tech-research）

已有 PRD（存在时必须检查并读取同名或相关文件，不要求新 feature 事先具备）：

• docs/prd/00-index.md — 正式 PRD 索引，存在时用于定位相关 PRD
• docs/prd/**/*.md — 同名或与当前 feature 的领域、流程、业务规则相关的正式 PRD
• .ai/prd/**/*.md — 同名或相关的 PRD 草稿；同名草稿用作更新基线

已有 user story（相关文件存在时读取，用于查重和关联）：

• docs/user-stories/**/*.md — 用户故事文档
• .ai/user-stories/**/*.md — draft 用户故事文档

写作规范（生成相应内容时读取）：

• ${CLAUDE_PLUGIN_ROOT}/guides/product/index.md — 产品规范入口
• ${CLAUDE_PLUGIN_ROOT}/guides/product/user-story.md — 用户故事规范

Decision Brief 缺失时先确认当前对话是否已有明确、可追踪的产品决策；若缺少会改变目标、范围或成功标准的裁决，提示先运行 /t-decision [feature]。技术预研缺失时，仅当技术未知会改变产品范围、业务规则、用户流程或验收目标，才提示先运行 /t-tech-research [feature]；否则继续创建草稿。独立需求文档、PRD、user story 或其索引缺失是正常的新建路径，不得据此要求用户提供文档；若已有相关 PRD，则必须读取。其他缺口按 Decision Exposure Gate 分类：可查事实由 skill 调查；需要用户裁决的信息必须提问；只有不需要用户选择的证据限制可以写入文档。

工作流程

1. 选择目标域并检查已有文件

先按 feature 检查 Decision Brief、Decision Log 和技术预研报告，按缺失输入规则处理。随后检查 docs/prd/00-index.md（如存在）及 docs/prd/、.ai/prd/：读取同名 PRD，并按上游产物中的领域、角色、流程和业务规则检索、读取相关 PRD；没有独立需求文档也不能跳过这一步。根据上游产物和已有 PRD 推断目标域，无法推断时用 AskUserQuestion 询问一次。检查 .ai/prd/<domain>/[feature].md 和 docs/prd/<domain>/[feature].md，按"更新行为"选择 create / draft-from-published / update 路径；同名文件都不存在时，在已查阅相关 PRD 的基础上走 create，并记录与已有能力的关系。

2. 收集信息

• 从 .ai/decision-log/$ARGUMENTS.md 提取 Active Decisions、Resolved Questions、Deferred Questions 和 Superseded Decisions；到达本阶段最迟解决点的 Deferred Question 必须在写 PRD 前解决。
• 从 .ai/decision/$ARGUMENTS.md 提取目标用户、问题陈述、范围方向、已确认产品决策、阻塞问题和给 PRD 的 Handoff。Verdict 为 Needs Clarification、Park 或 Reject 时停止并提示回到 /t-decision。若 Brief、现有 PRD 或 Tech Research 含已确认决策但账本缺少对应记录，按 decision-continuity-contract 初始化或补齐稳定 DEC ID；不得把 Open Questions、风险或假设升级成已确认决策。
• 如已存在 .ai/tech-research/$ARGUMENTS.md，从中提取技术需求（§1.2）、代码库评估（§2）、影响分析（§5）和 PRD 建议（§7）。
• 按 Confirmation Evidence 核对产品选择的依据；交付端等技术事实先查预研或代码，不作为默认提问项。
• 新建 user story 时还须覆盖用户价值、主验收场景和优先级（P0/P1/P2）。

3. 执行澄清门禁

按 PRD Clarification Gate 建立 Snapshot、补问并入账，达标后继续。

4. 检查、补齐并关联 user story

读取 ${CLAUDE_PLUGIN_ROOT}/guides/product/index.md 和 user-story.md；docs/user-stories/00-index.md、_README.md、_roles.md 存在时再读取。搜索与当前 feature、角色或领域相关的已有 docs/user-stories/、.ai/user-stories/ 文件；已有 PRD 已在步骤 1 查阅。相关 user story 不存在时继续生成本轮 user story 与 PRD 草稿。

执行：

• 已存在足够覆盖的 user story → 直接引用，不重复创建
• 缺少少量场景 → 写入或追加 .ai/user-stories/<domain>/<feature>.md
• 从已有草稿/正式 PRD 提取交叉引用和已有能力边界

新增 user story 必须遵循 ${CLAUDE_PLUGIN_ROOT}/guides/product/user-story.md 的结构和 GWT 风格验收标准，使用 user-story-template.md。

补齐后仍不足时：缺口影响产品语义、范围、角色、业务状态或验收目标 → 返回步骤 3，停止写入；产品语义已确认、仅缺独立 user story 文件 → 作为追踪覆盖工作补齐，不得写成待用户确认。

5. 生成 PRD 草稿

create 路径使用 template.md；draft-from-published 和 update 路径按"更新行为"逐章处理。不适用章节保留并标记"不适用"。写入后运行：

python ${CLAUDE_PLUGIN_ROOT}/scripts/check-decision-closure.py .ai/prd/<domain>/$ARGUMENTS.md

命中项按 Decision Exposure Gate 处理；扫描通过后再对照 Snapshot 检查 PRD 和 user story，遗漏或无依据的产品结论回到步骤 3。通过后方可交付；技术细节交给 /t-design。

6. 人机迭代

用户基于 PRD 草稿提出修改意见时：

• 表达方式调整 → 更新 Markdown PRD 草稿
• 产品语义调整 → 更新 PRD 草稿，并同步必要的 draft user story
• 与既有 Decision Brief、正式 PRD 或 user story 冲突 → 以用户最新确认意图为准；先创建新 DEC 并设置 Supersedes，再在草稿中记录覆盖关系，不得复用旧 DEC ID 改写历史

7. 收尾

完成后明确说明：

• user story 文件路径和变更方式（新增/追加）；若本轮产生 draft user story，说明其为 .ai/user-stories 候选来源，需在 /t-prd-publish 阶段合并到 docs/user-stories
• PRD 草稿路径、所属域、本轮路径类型（create / draft-from-published / update）
• Decision Log 路径和本轮新增/复用/替代的 DEC/Q ID
• 澄清覆盖结论和主要确认依据
• 验证风险或追踪覆盖工作；延期问题明确说明"无"或列出已登记的 Q ID
• 推断部分显式列出来源（现有文档 / 当前对话 / agent 自主决定 / 验证动作）
• 下一步：仍有会改变产品范围、业务规则、用户流程或验收目标的技术未知时，先运行 /t-tech-research [feature] 再重跑 /t-prd 收敛；否则高风险或复杂需求建议 /t-prd-check [feature]，简单需求可直接 /t-design [feature]

失败处理

• 缺失 feature 或文件无法写入：终止并报告
• Decision Brief 阻塞 PRD：终止并提示 /t-decision [feature]
• user story 信息不足：影响产品语义时返回步骤 3；不影响时补齐追踪文件或记录验证动作

质量门禁

• 新增 PRD 草稿前应尽量具备可引用的 user story
• needs_user_answer=0，且决策闭合扫描通过
• 所有影响 PRD 的 Active Decision 均在"已确认决策"中按 Decision ID 追踪
• 进入 /t-design 前，PRD 草稿与已有技术预研不得存在未解释冲突

附加资源

• PRD 模板：template.md
• User Story 模板：user-story-template.md