analyze-requirements

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Analyze Requirements

Skill：需求分析

Purpose

目的

Diagnose requirements-level problems and transform vague intent into validated, testable requirements. Guide developers from "I want to build X" to a clear problem statement, prioritized needs, explicit constraints, and bounded scope — all before any design or implementation begins.

诊断需求层面的问题，将模糊的意图转化为经过验证、可测试的需求。引导开发者从“我想做X”过渡到清晰的问题陈述、优先级明确的需求、明确的约束和界定的范围——所有这些都要在设计或实施开始前完成。

Core Objective

核心目标

Primary Goal: Produce a validated requirements document where every requirement is testable, scoped, and grounded in a real problem.

Success Criteria (ALL must be met):

✅ Problem articulated: A clear problem statement exists that does not reference any solution or technology
✅ Needs are testable with IDs: Every requirement has acceptance criteria and a unique
```
R-NN
```
ID (e.g. R-01, R-02); IDs sequential, no gaps or duplicates
✅ Constraints inventoried: Real constraints (budget, time, skills, dependencies) are separated from assumptions
✅ Scope bounded: V1 boundary is explicit with deferred items listed and triggers for reconsidering documented
✅ User confirmed: User explicitly approved the validated requirements (said "approved", "looks good", "proceed", or equivalent)
✅ Document persisted: Requirements document written to
```
docs/requirements-planning/<topic>.md
```
per
```
docs/ARTIFACT_NORMS.md
```
and committed

Acceptance Test: Can someone unfamiliar with the project read the requirements document and understand the problem, who has it, what "done" looks like, and what is out of scope — without asking clarifying questions?

主要目标：生成一份经过验证的需求文档，其中每一项需求都可测试、有明确范围，且基于真实问题。

成功标准（必须全部满足）：

✅ 问题已明确表述：存在清晰的问题陈述，未提及任何解决方案或技术
✅ 需求可测试且带ID：每项需求都有验收标准和唯一的
```
R-NN
```
ID（例如R-01、R-02）；ID连续，无空缺或重复
✅ 约束已梳理：真实约束（预算、时间、技能、依赖）与假设已分离
✅ 范围已界定：明确V1版本边界，列出延迟实现的项并记录重新考虑的触发条件
✅ 用户已确认：用户明确批准经过验证的需求（表示“批准”“看起来没问题”“继续推进”或类似表述）
✅ 文档已留存：需求文档已按照
```
docs/ARTIFACT_NORMS.md
```
写入
```
docs/requirements-planning/<topic>.md
```
并提交版本控制

验收测试：不熟悉项目的人阅读需求文档后，能否在无需询问澄清问题的情况下，理解问题是什么、受影响者是谁、“完成”的定义是什么以及哪些内容不在范围内？

Scope Boundaries

范围边界

This skill handles:

Vague intent → Validated requirements document
Problem discovery and articulation
Need clarification and acceptance criteria writing
Constraint inventory and assumption mapping
Scope definition and prioritization (V1 vs. later)
Requirements quality assessment (clarity, specificity, completeness)

This skill does NOT handle:

Design and architecture decisions (use
```
design-solution
```
)
Implementation planning or task lists (use implementation planning skills)
Code writing (use development skills)
Code review (use
```
review-code
```
)
Technology selection (mention constraints, but technology choice belongs to design phase)

Handoff point: When requirements are validated (all success criteria met), hand off to

design-solution

for design exploration, or to implementation planning if design is trivial.

本Skill处理以下内容：

模糊意图 → 经过验证的需求文档
问题发现与明确表述
需求澄清与验收标准撰写
约束梳理与假设映射
范围定义与优先级划分（V1版本与后续版本）
需求质量评估（清晰度、具体性、完整性）

本Skill不处理以下内容：

设计与架构决策（使用
```
design-solution
```
）
实施规划或任务列表（使用实施规划类Skill）
代码编写（使用开发类Skill）
代码评审（使用
```
review-code
```
）
技术选型（可提及约束，但技术选择属于设计阶段）

交接节点：当需求通过验证（所有成功标准均满足）时，将工作交接给

design-solution

进行设计探索；若设计非常简单，则交接给实施规划环节。

Use Cases

使用场景

New project kickoff: Developer says "I want to build X" — extract the real problem and validated needs before any design.
Feature request triage: Stakeholder submits vague feature request — clarify problem, scope, and acceptance criteria.
Scope creep prevention: Project keeps growing — apply prioritization and explicit V1 boundary.
Requirement validation: Existing requirements feel incomplete — diagnose which state they are in and progress them.
Constraint discovery: Mid-project surprise blockers — surface hidden constraints and assumptions before they derail work.

新项目启动：开发者说“我想做X”——在任何设计开始前，挖掘真实问题并明确经过验证的需求。
功能请求分类：利益相关者提交模糊的功能请求——澄清问题、范围和验收标准。
范围蔓延预防：项目持续扩张——应用优先级划分和明确的V1版本边界。
需求验证：现有需求感觉不完整——诊断其所处状态并推进完善。
约束发现：项目中期出现意外障碍——在问题影响工作前，发现隐藏的约束和假设。

Behavior

行为规范

Interaction Policy

交互策略

Defaults: Infer current state from input; start from earliest unresolved state
Choice options: One question at a time; offer
```
[A][B][C]
```
when possible
Confirm: Before exiting to design handoff; before writing requirements doc

默认规则：从输入中推断当前状态；从最早未解决的状态开始推进
选项设置：一次只提一个问题；尽可能提供
```
[A][B][C]
```
形式的选项
确认环节：在交接给设计环节前确认；在写入需求文档前确认

HARD-GATE: No Design Before Validation

硬性要求：验证完成前不得进行设计

text

DO NOT propose architecture, choose technologies, create designs,
or write code until requirements are validated.

Requirements describe PROBLEMS and NEEDS, not SOLUTIONS.
If a requirement mentions technology, it is a solution in disguise.

text

在需求通过验证前，不得提出架构方案、选择技术、创建设计或编写代码。

需求描述的是问题和需求，而非解决方案。
如果需求中提及技术，那它就是伪装成需求的解决方案。

Phase 0: Triage

阶段0：分类评估

Announce at start: "I'm using the analyze-requirements skill to validate requirements before any design or implementation."

Perform a quick quality assessment of the input:

Dimension	Score range	What to check
Clarity	0–100%	Is there a single unambiguous interpretation? Are terms defined?
Specificity	0–100%	Is context provided? Are success criteria mentioned? Is scope bounded?
Completeness	0–100%	Is all necessary information present? Are constraints mentioned?

Decision matrix:

Overall score	Action
< 40%	Start from State RA0 (problem discovery)
40–70%	Identify the earliest problem state and start there
> 70%	Validate quickly and focus on gaps

开始时告知：“我正在使用analyze-requirements Skill，在设计或实施前验证需求。”

对输入内容进行快速质量评估：

维度	评分范围	检查内容
清晰度	0–100%	是否存在唯一明确的解读？术语是否已定义？
具体性	0–100%	是否提供了上下文？是否提及成功标准？范围是否已界定？
完整性	0–100%	是否包含所有必要信息？是否提及约束？

决策矩阵：

整体评分	行动
< 40%	从状态RA0（问题发现）开始
40–70%	识别最早的问题状态并从该状态开始
> 70%	快速验证并聚焦于填补空白

Phase 1: Diagnose — Identify the Current State

阶段1：诊断——识别当前状态

Progress through states sequentially. Do NOT skip states — if the problem is not clear, do not discuss needs.

按顺序推进各个状态。不得跳过状态——如果问题不明确，不得讨论需求或范围。

State RA0: No Problem Statement

状态RA0：无问题陈述

Symptoms: Starting with a solution ("I want to build X"); feature list without problem grounding; "everyone needs this" reasoning; cannot articulate who has what problem.

Key questions (ask one at a time):

"What specific frustration or pain point led to this idea?"
"What are people (or you) doing today instead?"
"What happens if this does not exist? Who suffers and how?"
"If you are the user, what triggered you thinking about this now?"

Interventions:

Problem Statement Brief: capture who has what problem and why it matters
"Five users" test: name 5 specific people who would benefit (even if one is yourself)
Jobs-to-be-Done: "When I [situation], I want to [motivation], so I can [outcome]"
Problem archaeology: trace the origin back to a specific frustration event

Exit criteria: A problem statement exists that does not mention any solution or technology.

症状：从解决方案入手（“我想做X”）；功能列表未基于问题；“每个人都需要这个”的理由；无法说明谁遇到了什么问题。

关键问题（一次提一个）：

“是什么具体的困扰或痛点催生了这个想法？”
“你现在用什么方式替代？”
“如果这个东西不存在，会发生什么？谁会受影响，如何受影响？”
“如果你是用户，是什么促使你现在考虑这个？”

干预措施：

问题陈述摘要：记录谁遇到了什么问题以及该问题的重要性
“五个用户”测试：说出5个会从中受益的具体人物（哪怕其中一个是你自己）
待办工作法：“当我处于[场景]时，我想要[动机]，这样我就能[结果]”
问题溯源：将问题根源追溯到具体的困扰事件

退出标准：存在未提及任何解决方案或技术的问题陈述。

State RA1: Solution-First Thinking

状态RA1：先解决方案后问题的思维

Symptoms: Technology choices before problem clarity ("needs a database", "should use React"); requirements describe implementation rather than needs; cannot explain requirements without referencing technology.

Key questions:

"What is the need behind this feature?"
"If that technology did not exist, what would you still need?"
"Are you solving YOUR problem or copying someone else's solution?"
"Is this technology required (constraint) or just familiar (preference)?"

Interventions:

"Remove the solution" exercise: describe the need without ANY implementation words
Function extraction: rewrite each requirement as "The system must [verb]..." without technology terms
Constraint vs. preference distinction: separate hard constraints from defaults

Exit criteria: Every requirement describes a need, not an implementation. Technology references are either removed or explicitly documented as real constraints.

症状：在问题明确前就选择技术（“需要数据库”“应该用React”）；需求描述的是实现而非需求；无法脱离技术来解释需求。

关键问题：

“这个功能背后的需求是什么？”
“如果该技术不存在，你仍然需要什么？”
“你是在解决自己的问题，还是在复制别人的解决方案？”
“这项技术是必需的（约束）还是只是你熟悉的（偏好）？”

干预措施：

“移除解决方案”练习：不使用任何实现相关词汇来描述需求
功能提取：将每项需求重写为“系统必须[动词]……”，不包含技术术语
约束与偏好区分：将硬性约束与默认偏好分开

退出标准：每项需求都描述的是需求，而非实现。技术引用要么已移除，要么已明确记录为真实约束。

State RA2: Vague Needs

状态RA2：模糊需求

Symptoms: Cannot describe what "done" looks like; adjective-based requirements ("fast", "easy", "intuitive"); requirements that cannot be tested; "users should be able to..." without specifics.

Key questions:

"Can you give a specific example scenario?"
"What would a disappointing implementation look like vs. a great one?"
"What is the minimum that would satisfy this need?"
"How would you know if this requirement is met?"

Interventions:

Acceptance scenario writing: "Given [context], when [action], then [outcome]"
Specificity ladder: who specifically? doing what specifically? when specifically?
"Done looks like..." exercise: describe the smallest thing that would satisfy
Testability check: if you cannot write a test for it, you do not understand it yet

Exit criteria: Every requirement has acceptance criteria. No adjective-only requirements remain.

症状：无法描述“完成”的定义；基于形容词的需求（“快”“易用”“直观”）；无法测试的需求；“用户应该能够……”但无具体内容。

关键问题：

“你能给出一个具体的示例场景吗？”
“糟糕的实现和优秀的实现分别是什么样的？”
“满足该需求的最低标准是什么？”
“你如何知道该需求已满足？”

干预措施：

验收场景撰写：“给定[上下文]，当[动作]发生时，会产生[结果]”
具体性阶梯：具体是谁？具体做什么？具体什么时候？
“完成的样子是……”练习：描述能满足需求的最小成果
可测试性检查：如果你无法为需求编写测试，说明你还没真正理解它

退出标准：每项需求都有验收标准。不存在仅基于形容词的需求。

State RA3: Hidden Constraints

状态RA3：隐藏约束

Symptoms: Surprise dependencies appearing late; no explicit constraint inventory; assumptions treated as facts; discovering blockers mid-discussion.

Key questions:

"What external dependencies exist?"
"What resources, skills, and time do you actually have?"
"What would kill this project if it turned out to be true?"
"What are you assuming is true that you have not validated?"

Interventions:

Constraint Inventory: list budget, time, skills, dependencies, integrations as real constraints
Assumption mapping: separate validated facts from unvalidated assumptions
Risk pre-mortem: "It is 6 months later and this failed. Why?"
Dependency discovery: what must exist before this can work?

Exit criteria: A constraint inventory exists with explicit separation of real constraints vs. assumptions.

症状：后期才出现意外依赖；未明确梳理约束清单；将假设视为事实；讨论过程中发现障碍。

关键问题：

“存在哪些外部依赖？”
“你实际拥有哪些资源、技能和时间？”
“如果某件事被证明是真的，会导致项目失败，这件事是什么？”
“你假设哪些情况是真实的，但尚未验证？”

干预措施：

约束清单：将预算、时间、技能、依赖、集成项列为真实约束
假设映射：将已验证的事实与未验证的假设分开
风险事前分析：“6个月后项目失败了，原因是什么？”
依赖发现：在项目可行前，必须存在哪些条件？

退出标准：存在约束清单，明确区分真实约束与假设。

State RA4: Scope Creep

状态RA4：范围蔓延

Symptoms: Every feature feels equally important; no V1 boundary; "while we are at it..." additions; requirements expanding faster than they are satisfied.

Key questions:

"If you could only ship 3 things, what are they?"
"What could you cut and still solve the core problem?"
"What is the smallest useful version?"
"What triggers reconsidering deferred items?"

Interventions:

Cut-first approach: start with everything out, add back only what is essential
Force-rank: strict ordering, no ties
Walking skeleton: identify the thinnest useful version
MoSCoW: Must / Should / Could / Won't
Deferred features list with explicit triggers for reconsidering

Exit criteria: V1 boundary is explicit. Deferred items are listed with triggers. No ambiguity about what is in scope.

症状：所有功能都显得同等重要；无V1版本边界；“既然我们在做……不如顺便加上”的新增内容；需求扩张速度快于完成速度。

关键问题：

“如果你只能发布3个功能，会选哪3个？”
“砍掉哪些功能后，仍然能解决核心问题？”
“最小可用版本是什么？”
“重新考虑延迟项的触发条件是什么？”

干预措施：

先砍后加方法：先将所有功能排除在外，只添加必要的功能
强制排序：严格排序，不得并列
行走骨架：识别最精简的可用版本
MoSCoW方法：必须有/应该有/可以有/不会有
延迟功能列表：列出延迟项及重新考虑的明确触发条件

退出标准：V1版本边界明确。延迟项已列出并附带触发条件。范围无歧义。

State RA5: Requirements Validated

状态RA5：需求已验证

Indicators:

Problem statement exists without solution references
Every requirement is testable with acceptance criteria
Constraints are inventoried (real vs. assumed)
Scope is bounded with explicit V1 definition
Could explain to someone unfamiliar and have them understand the need

Next step: Hand off to

design-solution

with the Validated Requirements Document.

指标：

存在未提及解决方案的问题陈述
每项需求都可测试且有验收标准
约束已梳理（真实约束与假设分开）
范围已界定，有明确的V1版本定义
可以向不熟悉项目的人解释需求，对方能理解需求

下一步：将经过验证的需求文档交接给

design-solution

。

Phase 2: Validate — Confirm with User

阶段2：验证——与用户确认

Present the requirements summary in structured format (see Output section)
Ask for explicit approval: "Do these requirements accurately capture what you need?"
Iterate if needed: Return to the relevant state if gaps are found

以结构化格式呈现需求摘要（见输出部分）
请求明确批准：“这些需求是否准确捕捉了你需要的内容？”
必要时迭代：如果发现空白，返回相应状态重新处理

Phase 3: Persist — Write the Document

阶段3：留存——写入文档

Determine output location:
- Default:
```
docs/requirements-planning/<topic>.md
```
- Compatibility: existing projects using
```
docs/requirements/<topic>.md
```
  may keep that path temporarily
- Ask user if a different location is preferred
Write the document following the output template
Commit to version control
Announce completion and handoff

确定输出位置：
- 默认位置：
```
docs/requirements-planning/<topic>.md
```
- 兼容处理：现有项目若使用
```
docs/requirements/<topic>.md
```
  ，可暂时保留该路径
- 询问用户是否偏好其他位置
按照输出模板撰写文档
提交到版本控制
告知完成并交接工作

Input & Output

输入与输出

Input

输入

User request: Vague idea, feature request, problem statement, or existing requirements to validate.
Project context: Existing codebase, documentation, constraints (discovered during exploration).
User responses: Answers to diagnostic questions, feedback on assessments, approval of validated requirements.

用户请求：模糊的想法、功能请求、问题陈述，或需要验证的现有需求。
项目上下文：现有代码库、文档、约束（探索过程中发现）。
用户响应：对诊断问题的回答、对评估的反馈、对经过验证的需求的批准。

Output

输出

Validated Requirements Document

经过验证的需求文档

markdown

undefined

markdown

undefined

[Topic] Requirements

[主题] 需求

Date: YYYY-MM-DD Status: Validated Approved by: [User name or "User"]

日期： YYYY-MM-DD 状态： 已验证 批准人： [用户名或“用户”]

Problem Statement

问题陈述

[Who has what problem and why it matters. No solution or technology references.]

[谁遇到了什么问题以及该问题的重要性。不得提及解决方案或技术。]

Need Hierarchy

需求层级

Must Have (V1)

必须具备（V1版本）

ID	Need	Acceptance Criteria
R-01	[Testable need]	Given [X], when [Y], then [Z]
R-02	[Testable need]	[Measurable criterion]

ID	需求	验收标准
R-01	[可测试的需求]	给定[X]，当[Y]发生时，会产生[Z]
R-02	[可测试的需求]	[可衡量的标准]

Should Have (V1 if time permits)

应该具备（若时间允许则纳入V1版本）

ID	Need	Acceptance Criteria
R-03	[Testable need]	[Criterion]

ID	需求	验收标准
R-03	[可测试的需求]	[标准]

Could Have (Post-V1)

可以具备（V1版本之后）

ID	Need	Trigger to reconsider
R-04	[Deferred need]	[When to revisit]

ID	需求	重新考虑的触发条件
R-04	[延迟的需求]	[何时重新审视]

Constraint Inventory

约束清单

Real Constraints (Validated)

真实约束（已验证）

[Budget, time, skills, dependencies, integrations]

[预算、时间、技能、依赖、集成项]

Assumptions (Unvalidated)

假设（未验证）

[Assumptions that need validation, with plan to validate]

[需要验证的假设及验证计划]

Scope Definition

范围定义

In scope (V1): [Explicit list]
Out of scope: [Explicit list]
Walking skeleton: [Thinnest useful version]

纳入范围（V1版本）： [明确列表]
排除范围： [明确列表]
行走骨架： [最精简的可用版本]

Open Questions

未解决问题

[Any remaining unknowns with plan to resolve]

undefined

[所有待解决的未知问题及解决计划]

undefined

Conversation vs. File

对话内容与文档内容的划分

Goes to file	Stays in conversation
Problem statement	Five Whys exploration
Need hierarchy with acceptance criteria	Prioritization discussion
Constraint inventory	Assumption discovery dialogue
Scope definition	Cut/keep negotiations
Validated requirements	Clarifying questions

纳入文档	保留在对话中
问题陈述	五次追问探索
带验收标准的需求层级	优先级讨论
约束清单	假设发现对话
范围定义	功能取舍协商
经过验证的需求	澄清问题

Restrictions

限制条件

Hard Boundaries

硬性边界

No design before validation: Do NOT propose architecture, choose technologies, or create designs until requirements are validated.
No skipping states: If problem is unclear (RA0), do NOT discuss needs (RA2) or scope (RA4). Progress sequentially.
One question at a time: Do not overwhelm the user with multiple diagnostic questions in a single message.
Developer decides: Diagnose, question, and guide — the developer makes the final call on priorities and scope.
No vague acceptance: Do not accept adjective-based requirements ("fast", "intuitive") as complete. Push for testable criteria.
No solution language: Requirements must describe problems and needs, not implementations. Flag and rewrite solution-disguised requirements.

验证完成前不得设计：在需求通过验证前，不得提出架构方案、选择技术或创建设计。
不得跳过状态：如果问题不明确（RA0状态），不得讨论需求（RA2状态）或范围（RA4状态）。按顺序推进。
一次只提一个问题：不得在一条消息中向用户提出多个诊断问题，避免用户不知所措。
开发者做最终决定：进行诊断、提问和引导——但优先级和范围的最终决定权在开发者手中。
不接受模糊验收标准：不得将基于形容词的需求（“快”“直观”）视为完整需求。必须推动制定可测试的标准。
不得使用解决方案类语言：需求必须描述问题和需求，而非实现。标记并重写伪装成需求的解决方案。

Skill Boundaries (Avoid Overlap)

Skill边界（避免重叠）

Do NOT do these (other skills handle them):

Design and architecture: Proposing solutions, choosing technologies, creating design documents → Use
```
design-solution
```
Implementation planning: Creating task lists, file paths, code structure → Use implementation planning skills
Code writing: Writing any implementation code → Use development skills
Code review: Reviewing existing code → Use
```
review-code
```
Skill refinement: Improving skill documents → Use
```
refine-skill-design
```

When to stop and hand off:

User says "approved", "looks good", "proceed" → Requirements validated, hand off to
```
design-solution
```
User asks "how should we design this?" → Hand off to
```
design-solution
```
User asks "can you write the code?" → Requirements complete, hand off to development workflow (suggest design step if skipped)
User says requirements are "good enough" → Confirm all success criteria met, then hand off

不得执行以下操作（由其他Skill处理）：

设计与架构：提出解决方案、选择技术、创建设计文档 → 使用
```
design-solution
```
实施规划：创建任务列表、文件路径、代码结构 → 使用实施规划类Skill
代码编写：编写任何实现代码 → 使用开发类Skill
代码评审：评审现有代码 → 使用
```
review-code
```
Skill优化：完善Skill文档 → 使用
```
refine-skill-design
```

何时停止并交接工作：

用户表示“批准”“看起来没问题”“继续推进” → 需求已验证，交接给
```
design-solution
```
用户问“我们应该如何设计这个？” → 交接给
```
design-solution
```
用户问“你能写代码吗？” → 需求已完成，交接给开发工作流（若跳过设计环节则建议先进行设计）
用户表示需求“足够好” → 确认所有成功标准均满足后，再交接工作

Self-Check

自我检查

Core Success Criteria (ALL must be met)

核心成功标准（必须全部满足）

Problem articulated: Clear problem statement exists without solution or technology references
Needs are testable with IDs: Every requirement has acceptance criteria and a unique
```
R-NN
```
ID; IDs sequential, no gaps or duplicates
Constraints inventoried: Real constraints separated from assumptions
Scope bounded: V1 boundary explicit with deferred items and triggers documented
User confirmed: User explicitly approved the validated requirements
Document persisted: Requirements document written to
```
docs/requirements-planning/<topic>.md
```
and committed

问题已明确表述：存在未提及解决方案或技术的清晰问题陈述
需求可测试且带ID：每项需求都有验收标准和唯一的
```
R-NN
```
ID；ID连续，无空缺或重复
约束已梳理：真实约束与假设已分离
范围已界定：V1版本边界明确，延迟项及触发条件已记录
用户已确认：用户明确批准经过验证的需求
文档已留存：需求文档已写入
```
docs/requirements-planning/<topic>.md
```
并提交

Process Quality Checks

流程质量检查

States not skipped: Progressed through diagnostic states sequentially (did not jump from RA0 to RA4)
One question at a time: Did not overwhelm user with multiple questions per message
No solution language: Requirements describe needs, not implementations
Developer decided: Guided and questioned, but developer made final priority and scope calls
Adjectives resolved: No vague adjective-only requirements remain ("fast", "intuitive", "easy")
Assumptions separated: Unvalidated assumptions are flagged separately from real constraints
IDs reviewed: All requirement IDs follow
```
R-NN
```
format, are unique, and are used in cross-references within the document

未跳过状态：按顺序推进诊断状态（未从RA0直接跳到RA4）
一次只提一个问题：未在一条消息中向用户提出多个问题
无解决方案类语言：需求描述的是需求，而非实现
开发者做最终决定：进行引导和提问，但优先级和范围的最终决定由开发者做出
形容词类需求已解决：无模糊的仅基于形容词的需求（“快”“直观”“易用”）
假设已分离：未验证的假设已与真实约束分开标记
ID已审核：所有需求ID均遵循
```
R-NN
```
格式，唯一且在文档内的交叉引用中正确使用

Health Check Questions

健康检查问题

Before declaring requirements validated, ask yourself:

If this project failed, what would be the most likely reason related to requirements?
Is the developer building what they need or what they know how to build?
What is explicitly NOT in scope?
Is the scope achievable with the actual constraints?
What assumptions have not been validated?
Could someone unfamiliar explain the requirements back correctly?

在宣布需求已验证前，自问：

如果项目失败，与需求相关的最可能原因是什么？
开发者是在构建自己需要的东西，还是在构建自己知道如何构建的东西？
明确排除在范围外的内容是什么？
基于实际约束，该范围是否可实现？
哪些假设尚未验证？
不熟悉项目的人能否正确复述需求？

Acceptance Test

验收测试

Can someone unfamiliar with the project read the requirements document and understand the problem, who has it, what "done" looks like, and what is out of scope — without asking clarifying questions?

If NO: Requirements are incomplete. Return to the earliest unresolved state.

If YES: Requirements are validated. Persist and hand off to

design-solution

不熟悉项目的人阅读需求文档后，能否在无需询问澄清问题的情况下，理解问题是什么、受影响者是谁、“完成”的定义是什么以及哪些内容不在范围内？

如果不能：需求不完整。返回最早未解决的状态。

如果能：需求已验证。留存文档并交接给

design-solution

。

Examples

示例

Example 1: Greenfield Project — "I want to build a static site generator"

示例1：全新项目——“我想做一个静态网站生成器”

User: "I want to build a static site generator."

Agent announces: "I'm using the analyze-requirements skill to validate requirements before any design or implementation."

Triage: Clarity 30%, Specificity 10%, Completeness 10%. Start from RA0.

RA0 — Problem discovery:

Agent: "What specific frustration with existing static site generators led to this idea?"

User: "I'm tired of the complexity. I just want to write markdown and get HTML."

Agent: "What do you do today instead?"

User: "I use Hugo but spend more time debugging configuration than writing content."

Problem statement captured: "Solo content creator wastes time debugging SSG configuration instead of writing. Needs a zero-configuration path from Markdown to HTML."

RA1 — Solution-first check:

Agent: "You mentioned Hugo — is there anything about Hugo specifically that you need to preserve, or is 'Markdown → HTML' the core need regardless of tool?"

User: "Just Markdown to HTML. I don't care how."

Exit RA1: Need confirmed without technology lock-in.

RA2 — Specificity:

Agent: "What would 'done' look like for the simplest useful version?"

User: "I point it at a folder of .md files and get a folder of .html files with basic styling."

Agent: "How would you know the output is correct?"

User: "Each .md file produces one .html file. Links between pages work. It looks readable on mobile."

Acceptance criteria captured:

R-01: Each
```
.md
```
file → one
```
.html
```
file (1:1 mapping)
R-02: Internal links resolve correctly
R-03: Output is readable on mobile (viewport meta, readable font size)

RA3 — Constraints:

Agent: "What time and skills do you have for this?"

User: "Evenings and weekends, maybe 10 hours/week. I know JavaScript well."

Constraint inventory: Time: 10 hrs/week; Skills: JavaScript proficiency; Dependency: none identified.

RA4 — Scope:

Agent: "If you could only ship 3 features, what are they?"

User: "Markdown to HTML, basic CSS, and a dev server with live reload."

Scope defined:

V1 Must: Markdown→HTML, default CSS, dev server
Deferred: Themes, plugins, custom templates (trigger: after V1 is usable for 2 weeks)
Walking skeleton: CLI that converts one
```
.md
```
file to
```
.html
```

RA5 — Validated: Agent presents summary, user says "looks good." Document written to

docs/requirements-planning/static-site-generator.md

用户：“我想做一个静态网站生成器。”

Agent告知：“我正在使用analyze-requirements Skill，在设计或实施前验证需求。”

分类评估：清晰度30%，具体性10%，完整性10%。从RA0状态开始。

RA0——问题发现：

Agent：“现有静态网站生成器的哪些具体困扰催生了这个想法？”

用户：“我受够了复杂性。我只想写Markdown然后得到HTML。”

Agent：“你现在用什么替代方式？”

用户：“我用Hugo，但花在调试配置上的时间比写内容还多。”

已捕获问题陈述：“独立内容创作者浪费时间调试SSG配置，而非创作内容。需要一条从Markdown到HTML的零配置路径。”

RA1——先解决方案后问题的检查：

Agent：“你提到了Hugo——你是否需要保留Hugo的某些特性，还是核心需求只是‘Markdown→HTML’，无论用什么工具？”

用户：“只要Markdown转HTML就行。我不在乎用什么方式。”

退出RA1状态：需求已确认，无技术锁定。

RA2——具体性：

Agent：“最简单的可用版本的‘完成’定义是什么？”

用户：“我把它指向一个.md文件文件夹，就能得到一个带基础样式的.html文件文件夹。”

Agent：“你如何判断输出是否正确？”

用户：“每个.md文件生成一个.html文件。页面间的链接正常工作。在移动端看起来可读。”

已捕获验收标准：

R-01：每个
```
.md
```
文件 → 一个
```
.html
```
文件（1:1映射）
R-02：内部链接解析正确
R-03：输出在移动端可读（包含视口元标签、可读字体大小）

RA3——约束：

Agent：“你有多少时间和技能投入这个项目？”

用户：“晚上和周末，大概每周10小时。我很熟悉JavaScript。”

约束清单：时间：每周10小时；技能：熟练掌握JavaScript；依赖：未识别到依赖项。

RA4——范围：

Agent：“如果你只能发布3个功能，会选哪3个？”

用户：“Markdown转HTML、基础CSS、带实时重载的开发服务器。”

已定义范围：

V1版本必须具备：Markdown→HTML、默认CSS、开发服务器
延迟实现：主题、插件、自定义模板（触发条件：V1版本可用2周后）
行走骨架：将单个
```
.md
```
文件转换为
```
.html
```
文件的CLI工具

RA5——已验证：Agent呈现摘要，用户表示“看起来没问题”。文档已写入

docs/requirements-planning/static-site-generator.md

。

Example 2: Edge Case — Solution-Disguised Requirements

示例2：边缘场景——伪装成需求的解决方案

User: "I need a React app with a PostgreSQL database, GraphQL API, and Redis caching."

Agent announces: "I'm using the analyze-requirements skill to validate requirements before any design or implementation."

Triage: Clarity 60% (clear technologies), Specificity 20% (no problem stated), Completeness 15%. Start from RA0.

RA0 — Problem discovery:

Agent: "These are all technology choices. What problem are you trying to solve? Who has the problem?"

User: "Oh... I need to track inventory for my small business. I currently use spreadsheets and keep losing data."

Problem statement: "Small business owner loses inventory data due to spreadsheet limitations. Needs reliable inventory tracking."

RA1 — Solution-first cleanup:

Agent: "Let's rewrite the requirements without technology. 'React, PostgreSQL, GraphQL, Redis' are all solutions. What needs do they represent?"

Rewritten:

~~React app~~ → "Need a user interface accessible from multiple devices"
~~PostgreSQL~~ → "Data must survive server restarts and not be lost"
~~GraphQL API~~ → "Need to query inventory flexibly (by name, category, location)"
~~Redis caching~~ → "Frequently accessed data should load quickly"

Agent: "Is 'load quickly' testable? How fast is acceptable?"

User: "Under 2 seconds for the inventory list page."

Exit RA1: Requirements rewritten as needs. Technology choices deferred to design phase.

RA2–RA5: Continue through states. Final document captures needs without technology assumptions, allowing

design-solution

to explore the right solution (which might be a simple spreadsheet alternative, not a full-stack app).

用户：“我需要一个带PostgreSQL数据库、GraphQL API和Redis缓存的React应用。”

Agent告知：“我正在使用analyze-requirements Skill，在设计或实施前验证需求。”

分类评估：清晰度60%（技术明确），具体性20%（未陈述问题），完整性15%。从RA0状态开始。

RA0——问题发现：

Agent：“这些都是技术选择。你要解决的是什么问题？谁遇到了这个问题？”

用户：“哦……我需要为我的小企业跟踪库存。我现在用电子表格，总是丢失数据。”

问题陈述：“小企业主因电子表格的局限性而丢失库存数据。需要可靠的库存跟踪方案。”

RA1——清理先解决方案后问题的内容：

Agent：“我们来重写需求，去掉技术术语。‘React、PostgreSQL、GraphQL、Redis’都是解决方案。它们代表了哪些需求？”

重写后：

~~React应用~~ → “需要一个可从多设备访问的用户界面”
~~PostgreSQL~~ → “数据必须能在服务器重启后留存且不丢失”
~~GraphQL API~~ → “需要灵活查询库存（按名称、类别、位置）”
~~Redis缓存~~ → “频繁访问的数据应快速加载”

Agent：“‘快速加载’是可测试的吗？可接受的速度是多少？”

用户：“库存列表页面加载时间不超过2秒。”

退出RA1状态：需求已重写为纯需求表述。技术选择推迟到设计阶段。

RA2–RA5：继续推进各个状态。最终文档捕获了无技术假设的需求，允许

design-solution

探索合适的解决方案（可能是简单的电子表格替代方案，而非全栈应用）。

Example 3: Edge Case — Mid-Project Scope Creep

示例3：边缘场景——项目中期范围蔓延

User: "We started building a todo app but now it needs calendar integration, team collaboration, file attachments, and AI-powered task suggestions. We're 3 weeks behind."

Agent announces: "I'm using the analyze-requirements skill to validate requirements before expanding scope."

Triage: Clarity 50%, Specificity 40%, Completeness 30%. Scope creep symptoms — start from RA4 (earlier states likely resolved if 3 weeks in, but verify).

Quick RA0 check: "What was the original problem this todo app solves?"

User: "I need to stop forgetting tasks and deadlines for my freelance projects."

Problem confirmed — proceed to RA4.

RA4 — Scope creep intervention:

Agent: "If you could only ship 3 features from the full list, which 3 would solve the core problem of not forgetting tasks?"

User: "Basic task list, due dates with reminders, and... that's really it for now."

Agent: "So calendar integration, team collaboration, file attachments, and AI suggestions are all additions beyond the core problem. Should we defer them?"

Scope redefined:

V1 Must: Task CRUD, due dates, reminders
Deferred: Calendar integration (trigger: after using reminders for 1 month), collaboration (trigger: when freelance becomes team), attachments (trigger: user request), AI suggestions (trigger: 100+ tasks)
Walking skeleton: CLI or simple UI that creates tasks with due dates and sends reminder notifications

RA5 — Validated: Requirements refocused. 3-week delay becomes manageable. Document updated.

用户：“我们开始做一个待办应用，但现在它需要日历集成、团队协作、文件附件和AI驱动的任务建议。我们已经落后3周了。”

Agent告知：“我正在使用analyze-requirements Skill，在扩大范围前验证需求。”

分类评估：清晰度50%，具体性40%，完整性30%。存在范围蔓延症状——从RA4状态开始（项目已进行3周，早期状态可能已解决，但需验证）。

快速检查RA0状态：“这个待办应用要解决的原始问题是什么？”

用户：“我需要不再忘记自由职业项目的任务和截止日期。”

问题已确认——推进到RA4状态。

RA4——范围蔓延干预：

Agent：“如果你只能从所有功能中发布3个，哪3个能解决‘不忘记任务’的核心问题？”

用户：“基本任务列表、带提醒的截止日期，……目前真的只需要这些。”

Agent：“所以日历集成、团队协作、文件附件和AI建议都是核心问题之外的新增功能。我们应该推迟这些功能吗？”

已重新定义范围：

V1版本必须具备：任务增删改查、截止日期、提醒
延迟实现：日历集成（触发条件：使用提醒功能1个月后）、协作功能（触发条件：自由职业转为团队模式）、文件附件（触发条件：用户请求）、AI建议（触发条件：任务数量超过100个）
行走骨架：可创建带截止日期的任务并发送提醒通知的CLI工具或简单UI

RA5——已验证：需求已重新聚焦。3周的延迟变得可控。文档已更新。

Anti-Patterns

反模式

The Solution Specification

解决方案规格

Problem: Requirements describe implementation, not needs. "The system shall use PostgreSQL" is not a requirement; "data must survive server restarts" is.

Fix: For each requirement, ask "could this be satisfied a different way?" If yes, you captured implementation, not need.

问题：需求描述的是实现而非需求。“系统应使用PostgreSQL”不是需求；“数据必须能在服务器重启后留存”才是需求。

修复方案：对每项需求，问自己“能否用其他方式满足该需求？”如果可以，说明你捕获的是实现而非需求。

The Stakeholder Fiction

利益相关者虚构

Problem: Developer imagining requirements instead of discovering them. "Users will want..." without evidence.

Fix: If you are the user, be honest about YOUR needs. If building for others, talk to them or cite analogous evidence. Do not invent users.

问题：开发者凭空想象需求，而非发现需求。“用户会想要……”但无证据支持。

修复方案：如果你是用户，诚实地面对自己的需求。如果是为他人开发，与他们沟通或引用类似案例的证据。不得虚构用户。

The Infinite Backlog

无限待办清单

Problem: Requirements grow without prioritization. Everything is equally important.

Fix: Force-rank. If you could only ship ONE thing, what is it? Then two? This reveals actual priorities.

问题：需求无限制增长，未进行优先级划分。所有内容都同等重要。

修复方案：强制排序。如果你只能发布一个功能，会选哪个？然后是第二个？这能揭示真实的优先级。

The Premature Precision

过早的精确性

Problem: Specifying details that do not matter yet. Designing notification preferences before validating anyone wants notifications.

Fix: Stub uncertain areas with "TBD after [X] validated." Focus precision on V1 Must items.

问题：过早指定无关紧要的细节。在验证是否有人需要通知前，就设计通知偏好设置。

修复方案：对不确定的部分标记为“TBD，在[X]验证后确定”。将精确性聚焦于V1版本必须具备的项。

The Constraint Blindness

约束盲区

Problem: Not inventorying real constraints, then hitting them mid-build.

Fix: Explicit constraint inventory BEFORE finalizing requirements.

问题：未梳理真实约束，然后在构建过程中遇到障碍。

修复方案：在最终确定需求前，明确梳理约束清单。

Appendix: Integration Map

附录：集成映射

Upstream (feeds into this skill)

上游（为本Skill提供输入）

Source	When	What it provides
User request	New project or feature idea	Raw intent to analyze
Existing documentation	Mid-project validation	Partial requirements to diagnose

来源	时机	提供内容
用户请求	新项目或功能想法提出时	待分析的原始意图
现有文档	项目中期验证时	待诊断的部分需求

Downstream (this skill feeds into)

下游（本Skill为其提供输入）

Target skill	When	What it receives
`design-solution`	Requirements validated	Validated Requirements Document as design input
Implementation planning	Design is trivial	Validated requirements with scope and constraints

目标Skill	时机	接收内容
`design-solution`	需求已验证时	经过验证的需求文档，作为设计输入
实施规划	设计非常简单时	带范围和约束的经过验证的需求

Handoff contract

交接契约

This skill outputs	Target skill expects
Problem statement	Design context
Need hierarchy with acceptance criteria	Functional requirements
Constraint inventory	Architecture constraints
Scope definition (V1 boundary)	Design scope

本Skill输出内容	目标Skill期望内容
问题陈述	设计上下文
带验收标准的需求层级	功能需求
约束清单	架构约束
范围定义（V1版本边界）	设计范围