---
name: requirement-analysis
description: 基于现有代码与业务上下文澄清需求；可独立产出需求分析，或在 Brainstorming 中作为只读探针发现下一项高价值需求缺口。
metadata:
  author: "devkeel"
  version: "3.1.0"
---

# 需求分析

把模糊意图收敛成可决策、可验收的需求结果。

## 调用方契约

先识别调用模式：

- `probe`：由 Brainstorming 调用，只返回候选 gap 与证据，不向用户提问、不写文件、不生成报告；
- `deliverable`：用户明确要求需求分析文档或调用方提供需求类 artifact 时，按下述结构交付。

OpenSpec design/specs/tasks 的投影阶段不得调用本 skill 补充语义。若投影发现需求缺口，必须停止并
交回 Brainstorming；不能利用模板空位自行扩散需求。

- 调用方提供具体模板，或 artifact instruction 已明确标题、字段与顺序时，以该结构为准；
  不追加默认模板章节，不另建平行报告。
- 只有输出路径或内容约束、没有具体结构时，不视为已提供模板；按默认模板交付到指定位置。
- 同一 Agent 上下文仍热且没有压缩、外部编辑或事实不确定时，复用已有调查与决策。
- 独立调用且用户未指定文件时，先在回复中给结果；需要持久化时遵循项目文档位置约定。
- 只负责需求分析。完成后返回调用方，不自动调用 Explore、technical-design、tasks 或 apply。

## Probe 输出契约

仅在 probe 模式按 Brainstorming 传入的讨论深度、目标与边界、已有决定、仓库依据和探查重点工作：

- Lite：围绕当前方向，定向检查目标、边界、行为、验收或外部约束的关键缺口；
- Full：额外检查问题定义与隐含假设、遗漏场景，以及其他满足目标的合理方向；只展开相关维度；
- 未传深度时保持定向补缺；不自行切换讨论档位，不改变独立 deliverable 模式。

只返回内部候选列表，每项包含：

- 尚未确定的一件事；
- 属于当前范围的阻塞缺口，还是扩大范围才有价值的可选建议；
- 它可能改变的目标、范围、行为、验收或外部约束；
- 仓库证据与当前猜测；
- 影响和不确定性。

不要排序后一次展示给用户。调用方会与 technical-design 的 gap 合并去重，并且只询问最高价值的
一项。能从仓库查明、已有 D-* 覆盖或属于 A-* 自主范围的内容不算 gap；新证据揭示已确认决定
存在冲突或风险时，指出证据并交回 Brainstorming。可选建议不自动成为 O-* 或新需求；没有候选
缺口时返回简短检查结论与依据，不为了 Full 制造问题或替代方向。

## 输出结构优先级

1. 用户或调用方提供的具体模板优先。保留其标题、顺序、必填字段和格式；只在模板允许时
   合并或省略章节。
2. artifact instruction 明确给出结构时，将其视为调用方模板；仅有目标、约束或输出路径时，
   将这些内容作为写作约束，而不是结构模板。
3. 没有提供模板时，读取 `references/default-template.md`，按需求复杂度裁剪默认模板；核心
   结论必须保留，不适用的可选章节不输出。

## 工作方式

### 1. 建立现状

先区分已知事实、仓库可查事实和真正未知项。默认由当前 Agent 做聚焦调查：读取生效的
项目约束、需求触点的入口、直接依赖、现有行为和邻近测试。不要全仓扫描或读取无关历史。

只有调查面确实很宽、能拆成相互独立的只读问题且并行收益明显时，才可使用调查
subagent；主 Agent 必须整合证据。不得把提问、决策或写报告整体外包，也不得分派实现。

### 2. 澄清实质未知项

仅询问无法从上下文或仓库查明、且答案会改变以下任一结果的问题：

- 目标、范围或非目标；
- 用户可观察行为和验收；
- 外部契约、兼容、迁移或回滚；
- 权限、不可逆操作或关键风险承担。

没有实质未知项时直接推进。不要为了遵守固定轮次逐章确认，不要求每题都有多个方案，
也不要询问仓库已经能回答的问题。存在多个真实可选方向时，给出差异、代价和建议。

### 3. 内部推演

按需使用 5W1H、MECE、INVEST、SCAMPER、失败路径或边界推演，但不输出方法论清单、
覆盖矩阵或“已分析全部维度”的证明。优先检查：

- 谁在什么条件下触发什么行为，成功结果如何观察；
- 数据为空、重复、越界、并发、失败或恢复时怎样处理；
- 与现有行为、外部消费者、权限和数据生命周期的边界；
- 哪些约束必须验收，哪些只是实现偏好。

### 4. 交付结果

按上述优先级选择结构。默认模板承接以下结果，不强制空章节：

- 一句话目标与当前问题；
- 现状事实和受影响角色；
- 范围、非范围与用户可观察用例；
- 明确、可执行的验收标准；
- 约束、兼容/迁移要求和失败边界；
- 已确认决策、主要风险和仍需外部决定的事项。

流程、状态、角色或边界关系用 Mermaid 能明显提高理解时使用 Mermaid。避免固定篇幅、
逐维度表格和无法验证的“优化”“提升”等表述。每项验收应能由测试、操作或可观察事实
判定。

## 完成条件

输出应让后续设计或任务拆分可以直接回答：要实现什么、明确不做什么、怎样算完成、哪些
风险和外部决定仍未解决。给出关键仓库依据和非阻塞假设，然后停止并把控制权交还调用方。