Testspec New

testspec-new：新建测试工作（需求文档）

铁律：没有可追溯需求来源或明确的“信息不足”标记时，绝不能创建 TestSpec change；也绝不能仅靠重新排版就把原始 PRD 变成 requirements.md。

TestSpec 新建进度：

- [ ] 步骤 1：确定 change 名称 ⚠️ 必需
- [ ] 步骤 2：评估输入材料 ⚠️ 必需
- [ ] 步骤 3：创建 change 工作区
- [ ] 步骤 4：写入包含协作检查点的 proposal.md
- [ ] 步骤 5：有原始 PRD 材料时执行 PRD intake 并写入 requirements.md
- [ ] 步骤 6：生成 requirements.md 后复核其质量
- [ ] 步骤 7：写入 context 元数据并报告下一步

职责

新建一次 TestSpec 测试工作：创建变更目录并编写测试提案初稿，在 proposal 中关联或引用需求文档（PRD、用户故事、接口说明等）。当输入是已有 PRD 或需求片段时，额外执行 PRD Intake：先审查模糊和缺失，再把材料净化成 requirements.md，作为后续 testspec-analysis 的高质量需求源。

testspec-new 只负责准备可信需求源；不要在本阶段做测试风险拆解、测试点设计或用例生成。

若当前变更目录已存在，且用户是在补充、修改、删除或澄清 PRD/API/UI/产品口径，改用 testspec-update 做需求源口径收敛，不要重新创建变更。

共享规则源

• proposal 模板：references/proposal-template.md
• requirements 模板：references/requirements-template.md
• 输出契约：../_testspec-shared/references/output-contracts.md
• 上下文协议：../_testspec-shared/references/context-protocol.md
• 来源与信任：../_testspec-shared/references/source-provenance.md
• 问题状态机与 frontier：../_testspec-shared/references/interrogation-protocol.md

确定变更名

• 从用户输入中提取被测对象（功能名、模块名、版本号等）。
• 将名称规范为短名：英文或拼音，空格与特殊字符替换为 -（如「用户登录」→ user-login，release 2.0 → release-2.0）。

执行步骤

1. 确保根目录存在：若项目下没有 testspec/changes/，直接创建（mkdir -p testspec/changes）。

2. 创建变更目录：testspec/changes/<name>/，以及子目录 specs/、artifacts/。

3. 编写 proposal.md：在变更目录下创建 proposal.md。

   模板见 references/proposal-template.md，核心字段：

   • 被测对象（功能/模块/版本）
   • 关联需求文档：路径或链接（PRD、用户故事、接口文档等）
   • 测试目标与原因
   • 可选：关联的 OpenSpec

4. 协作检查点（写入 proposal.md 末尾、context 元数据之前）：

   测试质量的上限取决于测试开始前的信息对齐程度。如果产品、开发、测试三方对需求范围和技术约束的理解不一致，后续分析和用例生成会建立在错误的假设之上。这个检查点的目的不是设置审批门禁，而是让 proposal 的信息质量从源头得到保障，减少下游返工。

   ## 协作确认
   - [ ] 产品已确认需求范围和验收标准
   - [ ] 开发已确认技术约束和可测试性（如：是否有测试环境、数据准备方式、已知的技术限制）
   - [ ] 测试分析前需澄清的关键问题已列出（→ 将传递给 testspec-analysis 的质询清单）
   

   使用说明：

   • 默认生成为未勾选状态，不阻塞流程
   • 用户可手动勾选确认，也可跳过直接进入 testspec-analysis
   • 若全部未勾选进入 analysis，testspec-analysis 会在信号检测中识别到 material_quality 偏低，自动加深质询力度
   • 第三项"关键问题"若已填写，将直接传递给 testspec-analysis 作为质询清单的种子输入

5. PRD Intake（按需）：若用户提供已有 PRD 内容、PRD 链接/路径可读取内容，或明确要求审查/补全 PRD，则创建 requirements.md。

6. 需求质量复核（按需）：若生成 requirements.md，执行六维质量复核并写入文档。

7. 告知用户：变更目录路径、需求质量和 strategy requirement；下一步执行 testspec-analysis。

PRD Intake 模式

触发条件：

• 用户粘贴已有 PRD、需求片段、用户故事或功能清单
• 用户提供可读取的 PRD/需求文档路径或链接
• 用户要求「审查 PRD」「补全需求」「整理成 requirements.md」

执行规则：

1. 先挑刺，不整理：先识别模糊表述、隐含依赖、缺失验收条件、边界不清、合规/权限/数据隔离等隐藏假设。
2. 只描述做什么：requirements.md 不写 Redis、MQ、数据库表、接口拆分、算法选型等实现方案；未确认项进入 question graph 或风险点。
3. 功能必须可验收：功能列表每一条必须同时包含行为和验收条件；缺少标准的条目不得伪装完成，按影响进入 question graph 或风险点。
4. 边界必须显式化：明确本期不做什么、输入输出边界、格式/容量/权限/数据隔离边界。
5. 交互追问一次一个问题：需要用户补信息时，一次只问最高影响的一个问题；可以在 requirements.md 中保留完整澄清清单，但对话中只推进一个阻塞点。
6. AI/算法类需求要有评估标准：涉及搜索、推荐、问答、识别、生成等效果型能力时，验收条件必须包含样本集/benchmark、通过阈值、人工复核或失败处理标准；缺失则标为风险。
7. 输出产品问题清单：当 readiness 不足或存在阻塞 analysis 的 active decision 时，输出当前 decision frontier；对话中默认只追问最高影响问题。
8. 默认 PRD-first：PRD、产品回答和验收规则是默认需求源。不得要求代码访问；只有用户主动提供代码或明确要求代码调查时，才按 ../_testspec-shared/references/source-provenance.md 记录可选代码证据。

审查维度

• 模糊词：合理、快速、稳定、友好、相关、适当、尽快、准确等不可直接验收的描述
• 隐含依赖：权限模型、租户/数据隔离、审计合规、通知链路、外部系统、内容安全
• 验收缺口：未说明完成标准、错误处理、边界值、容量限制、兼容范围、超时和重试
• 范围边界：本期不支持的角色、格式、平台、流程、异常数据和历史兼容
• 风险点：会影响开发排期、测试验收、合规或上线质量的未确认项

requirements.md 写入规则

按 references/requirements-template.md 生成 requirements.md。材料不足时也可以生成，但必须：

• 在「功能列表」中只保留已有明确验收条件的条目
• 「功能列表」中的每条功能必须使用 REQ-001 形式编号，并保留来源（原 PRD 章节/第 N 条/链接锚点等）
• 按共享 interrogation 协议建立稳定 question graph；Fact 由 Agent 查证，Decision 由用户/产品裁决
• 在「风险点」中使用 RISK-001 形式编号，并说明影响、决策条件或备选处理
• 在末尾播种 context schema v2，包含 questions、strategy_requirement、source_revision、质量字段和 stale envelope；完整字段以模板为准

需求质量复核

生成 requirements.md 后，按六维给出 0-100 分：完整性、清晰性、一致性、可测试性、可追溯性、可行性。总分为六维平均值。

结论规则：

• ready_for_analysis：总分 >= 90，且无阻断级澄清项
• needs_clarification：总分 75-89，或存在会影响测试设计但可继续分析的问题
• needs_revision：总分 60-74，需求需明显补写后再继续
• blocked：总分 < 60，或核心范围/验收标准缺失导致无法进入后续流程

复核要求：

• 每个扣分原因必须指向具体 REQ-ID、章节或原 PRD 位置
• 风险点不能只登记，必须说明影响、决策条件或备选处理；缺失则扣完整性/可行性
• 发现技术词混入（如缓存、索引、异步、向量、队列、数据库、接口、算法）时，判断它是否为业务可见概念；若只是实现方案，改写成用户可感知行为并扣清晰性
• 执行“陌生人测试”：5 分钟内能否从文档回答系统做什么、谁在用、本期不做什么、成功/失败怎么算、最大风险是什么；答不上来则扣清晰性/完整性
• 总分低于 90 时，不得把 readiness 标为 ready_for_analysis

产品问题清单

当 readiness != ready_for_analysis 或存在阻塞 analysis 的 active decision 时，最终回复必须输出当前 frontier 中可直接转发给产品的问题：

## 可复制给产品的问题清单
1. [P0/P1/P2] <问题>（影响：<阻塞的分析/验收判断>；需要产品给出：<规则/范围/样例/口径>）

排序规则：先按阻塞阶段，再按测试影响排序；每个问题关联 REQ/RISK/来源，只展示依赖已解决的 decision frontier。

反模式

• 不把原始 PRD 改个格式就当 requirements.md
• 不为缺失验收条件的功能补编规则
• 不把实现方案写成需求事实
• 不在总分低于 90 时标记 ready_for_analysis
• 不生成无 REQ-ID 或无来源的功能条目
• 不在需求未 ready 时只说“请补充需求”，必须给出可复制给产品的问题清单

材料评估与工具使用

在编写 proposal.md 之前，对用户提供的材料进行评估：

信息密度判断

• 完整 PRD：用户提供了详细的需求文档链接或内容 → 在 proposal 中完整引用，并触发 PRD Intake 生成 requirements.md
• 简短描述：用户只说了功能名称或一句话 → 在 proposal 中标注信息不足，建议补充
• 代码仓库：仅当用户显式要求代码校准时，先创建本 change，再路由到 testspec-code-calibrate；本 skill 不直接扫描代码或从代码生成 canonical requirements

工具自主使用

• 若用户提供了 PRD 链接 → 抓取链接内容，提取关键信息写入 proposal
• 若用户明确要求从代码恢复需求 → proposal 标记信息不足，完成 workspace 后运行 testspec-code-calibrate recovery；草稿经产品确认后交 testspec-update
• 若用户要求用代码核对已有 PRD → 完成当前 PRD intake 后运行 testspec-code-calibrate comparison；本 skill 不读取代码
• 若用户提供了设计稿链接 → 抓取可访问内容，提取交互流程

上下文播种

在 proposal.md 末尾，按 ../_testspec-shared/references/context-protocol.md 播种元数据：

<!-- testspec-context
{
  "context_schema_version": 2,
  "source_skill": "testspec-new",
  "canonical_source_policy": "prd-first",
  "evidence_sources": [{"type": "prd", "source_ref": "<来源>", "authority": "canonical", "scope": ["product-behavior"]}],
  "questions": [{"id": "Q-001", "kind": "decision", "status": "open", "question": "<问题>", "depends_on": [], "blocks_stages": ["analysis"], "recommendation": {"value": "<建议答案>", "status": "proposed"}, "resolution": null}],
  "strategy_requirement": {"status": "<required/skipped>", "reasons": ["<原因>"]},
  "material_quality": "<high/medium/low>",
  "signals_detected": ["<从材料中发现的关键信号>"],
  "requirements_intake": {
    "generated": "<true/false>",
    "path": "<requirements.md 或空>",
    "open_question_count": "<阻塞 analysis 的 active question 数量>"
  },
  "source_revision": {
    "version": 1,
    "summary": "<本轮需求源口径摘要>",
    "updated_by_skill": "testspec-new"
  },
  "stale_downstream_artifacts": [],
  "requirement_quality": {
    "overall_score": "<六维平均分或空>",
    "readiness": "<ready_for_analysis/needs_clarification/needs_revision/blocked 或空>"
  }
}
-->

产物

• testspec/changes/<name>/proposal.md（含上下文元数据）
• testspec/changes/<name>/requirements.md（可选；当已有 PRD/需求片段可净化时生成）
• testspec/changes/<name>/specs/（空目录）
• testspec/changes/<name>/artifacts/（空目录）