requirement-analysis

Requirement analysis (requirement-analysis)

Answer "What exactly does this requirement need to do" — establish a correct understanding of the system, rather than writing tests.

• Input: PRD, design documents, API documentation, Bugs, Issues, code repositories; in bypass scenarios, consume exploratory-testing 's exploration notes (system understanding + risk list)
• Output (written to disk)：{项目}/需求模型.md— organized according to the Schema below, including clarification records and user rulings
• Boundaries: does not produce test cases (→ test-case-writing); items that remain ambiguous after clarification are truthfully marked in open_questions，do not guess

When to Use

• Obtain the PRD/design document and need to systematically understand "what exactly this requirement needs to do" before entering testing
• Multiple input sources (documents + code + Bug tickets) need cross-checking to expose contradictions and gaps
• For test-strategy / test-case-writing prepare structured requirement model input

When NOT to Use

• End-to-end testing of the entire requirement → qa orchestration
• Already have a requirement model, directly write test cases → test-case-writing(its phase one includes inline lightweight study; if sufficient, there is no need to model first)
• "How should this feature be tested" → test-strategy
• Completely no documentation and unfamiliar system → first go through exploratory-testing exploration, then come back to modeling

Requirement model Schema (output structure)

requirement_model:
  goal:                     # 需求目标（一句话 + 成功标准）
  scope:                    # 功能范围（含明确的非目标）
  roles: []                 # 角色 → 能做什么 / 不能做什么
  inputs: []                # 输入（来源、格式、约束）
  outputs: []               # 输出（去向、格式、消费方）
  states: []                # 状态与流转（状态A --事件--> 状态B，逐条）
  rules: []                 # 业务规则，每条带 evidence（文档章节或 文件:行）
  exceptions: []            # 异常情况（错误场景的预期行为）
  dependencies: []          # 依赖关系（上下游系统、共享数据、时序依赖）
  open_questions: []        # 不明确事项 → 澄清记录（含用户裁决）

Evidence annotation (at this point load ../core/evidence.md): each item of rules / states / exceptions is annotated with evidence (level E0–E4 + source); user rulings during the clarification step are recorded in the ruling field of open_questions, and subsequent skills must not overturn them with code.

Workflow

1. Input collection and inventory

• Inventory available input sources: PRD / design documents / API documentation / Bug tickets / FAQ / meeting minutes / code repositories
• If there is a code repository → proactively request it (path + branch + change scope + comparison baseline base— phase 7 regression scope is delimited by it), code is the highest source of static facts; branch name + commit (or fetch time) + comparison baseline are recorded in the header of the requirement model file, and before the pipeline continues or enters the execution phase, first verify that the branch has not changed — conclusions from modeling an old branch cannot be reused; if it has changed, mark the affected fields and re-check
• If there are exploration notes (探索笔记_{主题}.md) → consume their "system understanding" and "risk list" as modeling input
• Missing input items are listed in open_questions(e.g., "no performance metrics document")

2. Initial reading and element extraction

Read through each document and collect elements according to the ten fields of the Schema:

• goal / scope: goals and success criteria; explicit "non-goals" statements are collected separately (to be converted into verification boundaries later)
• roles: roles × what they can / cannot do (the prototype of the permission matrix)
• inputs / outputs: where data comes from, where it goes, who consumes it (output with no downstream consumption is a falsification clue)
• states: states and transition edges; when code is available, extract from code state fieldsactualstate machine, compare with the documentation, and record differences in clarification
• rules: business rules are numbered one by one and annotated with evidence
• exceptions / dependencies: error scenario behavior, upstream and downstream dependencies

3. Consistency check (conflict discovery)

• Internal document contradictions: descriptions of the same feature in different places in the same document are inconsistent
• Cross-document contradictions：PRD and technical design rules / process / fields are inconsistent
• Documentation vs code(when code exists): according to ../core/evidence.md static adjudication rules—default to code as authoritative, record deviations and submit clarifications

4. Clarification (⏸ checkpoint, no hard guessing)

The single authoritative source for triggers and scanning is in ../core/clarify-pattern.md(loaded at this point)：basic triggers follow its "when must ask" 6 items, deep scanning follows its "nine categories of requirement ambiguity missed patterns" A–I screen materials category by category(this section no longer maintains an independent checklist, to prevent cross-skill criteria divergence), hits must enter the clarification list—among them category I (NFR metric gaps) is reminded separately: performance/compatibility descriptions commonly say "fast, stable, supports multiple platforms" without numeric values; ask for metrics or explicitly exclude, choose one of the two, skipping is not allowed.

Question format and adjudication persistence are likewise uniformly according to ../core/clarify-pattern.md(each item independently becomes a card, a single simple question uses its compact single-line template), wait for the user's reply, do not assume on your own.

User adjudications are recorded in open_questions(question / adjudication / basis), and have final adjudicative force.

5. Persistence and delivery

• Write according to Schema {项目}/需求模型.md; items still ambiguous after clarificationremain in open_questions and are marked "unadjudicated", do not hard-guess and fill into rules
• At delivery give downstream (test-strategy / test-case-writing) a one-sentence index: model path + number of unadjudicated items

Common Mistakes

Error	Consequence	Correct practice
Hard-guess ambiguous items and fill into rules	The model is based on wrong assumptions, all downstream is contaminated	Ambiguous items go into open_questions, wait for user adjudication
Only read PRD without reading code (when code exists)	Rules are disconnected from implementation	Code takes priority, documentation is downgraded to reference (../core/evidence.md）
Mix testing ideas into the requirement model	Overstepping responsibility (that is the business of strategy/test cases)	The model only describes "what the system is / what it wants", not "how to test it"
User adjudications are not persisted	Subsequent skills re-initiate the same questions or overturn adjudications	Adjudications are recorded in open_questions, the file is the pipeline state
Non-goal statements are ignored	Test scope is mistakenly expanded, missing "verification of constraints"	Non-goals are separately included in scope
Performance/compatibility with only qualitative descriptions is let through	NFRs without metrics are untestable, thresholds are improvised during execution	Screen by the nine categories, category I: ask for numeric values or explicitly adjudicate "not verified in this version"
When new facts appear, still cling to old adjudications	The model continues downstream based on invalidated assumptions	Trigger adjudication reopening: present new and old evidence and re-clarify, reopening starts a new entry without overwriting
Empty fields and missed extraction cannot be distinguished	Downstream cannot tell whether it is "absent" or "not checked"	Self-check before persistence: empty fields are marked "checked, no such elements"