requirements-freeze

Requirements Freeze

Drive requirements from vague idea to a frozen, reviewed spec using brainstorming, then lock it down.

Hard Gate

Prerequisite: project-governor:project-init must be complete.

• Verify: docs/governor/project.yaml exists with current_phase: init or earlier cycle phase.

PDCA Cycle

digraph req_pdca {
    rankdir=LR;
    node [shape=box, style=filled];
    "P: Define requirements scope" [fillcolor="#E3F2FD"];
    "D: Brainstorm + write spec" [fillcolor="#E8F5E9"];
    "C: Gate-check requirements" [fillcolor="#FFF3E0"];
    "A: Freeze or rework" [fillcolor="#F3E5F5"];

    "P: Define requirements scope" -> "D: Brainstorm + write spec" -> "C: Gate-check requirements" -> "A: Freeze or rework";
    "C: Gate-check requirements" -> "D: Brainstorm + write spec" [label="fail", style=dashed];
}

Plan

• 目标：从模糊想法中提炼出可冻结的需求规格
• 输入：project.yaml 中的项目描述 + 用户口述
• 验收标准：需求规格覆盖 functional/non-functional/constraints，无 TBD

Do

1. Load context — Read docs/governor/project.yaml for project type and description 语言要求：本次委托产出的所有文档必须使用中文撰写。如果被委托的 skill 输出英文内容，在保存为 artifact 之前必须翻译为中文。专业术语可在括号内保留英文原文。

   增量模式检测：如果 project.yaml 中 existing_project: true，或 docs/governor/specs/ 中存在 *现状分析*.md 文件，则进入增量模式。读取现状分析文档作为 brainstorming 的输入基础。

2. Delegate to superpowers:brainstorming — Invoke the brainstorming skill to collaboratively refine requirements, 严格遵循渐进式提问原则：

   • 逐个提问，不要批量抛出：每次只问 1 个问题（最多 2 个强相关问题），等用户回答后再决定下一个问题
   • 前答决定后问：每个问题的答案会影响后续问题的方向和内容。例如：
     • "核心用户是谁？" → 答案决定接下来问哪些功能场景
     • "主要解决什么问题？" → 答案决定追问哪些非功能性约束
     • "部署环境是什么？" → 答案决定需要问哪些性能/安全要求
   • 先搞清大方向，再追问细节：按 "问题域 → 用户场景 → 功能边界 → 约束条件" 的层次递进，不要在方向未定时就问细节
   • 跳过不相关的问题：如果前面的答案已经隐含了某些信息，直接跳过对应的问题，不要机械地问一遍

   增量模式（已有项目）：将现状分析文档作为 brainstorming 的初始上下文。提问策略调整为：

   • 起步问题："基于现有系统的分析，你接下来想改进或新增什么功能？"
   • 后续问题围绕增量需求展开，不再从零开始探索问题域
   • 需求规格中应包含「现有系统概述」章节

3. Redirect spec output — When brainstorming produces its spec, move/rewrite it to docs/governor/specs/YYYY-MM-DD-<project-name>-requirements.md

4. Adapt spec template — Ensure the frozen spec includes:

   • Problem Statement — What problem are we solving and for whom
   • Scope — In-scope / out-of-scope boundaries
   • Functional Requirements — Numbered list with acceptance criteria
   • Non-Functional Requirements — Performance, security, reliability constraints
   • Constraints & Assumptions — Technology choices, timeline, dependencies
   • Type-specific sections — Type A: CLI interface contract; Type B: user personas + core user flows
   • 现有系统概述（仅增量模式）— 基于现状分析文档，概述当前系统架构、已有功能和接口，为后续设计阶段提供上下文

Check (阶段门禁)

Dispatch gate-checker agent against shared/gate-templates/requirements-gate.md:

• All required sections present and substantive
• Type-specific sections match project type
• No placeholder content ("TBD", "TODO", "fill in")
• Each requirement is testable
• No internal contradictions

Gate verdict → PASS / CONDITIONAL / FAIL

Act

• PASS: Append requirements to phases_completed, set current_phase: requirements. Write gate record to docs/governor/gates/gate-requirements-cycle-N.md. 更新 docs/governor/INDEX.md：更新当前阶段，追加产物记录行（含规格路径和一句话说明）。
  • If auto: true in project.yaml: Automatically invoke project-governor:flow-design.
  • If auto: false: Prompt: "Requirements frozen. Next: invoke project-governor:flow-design"
• CONDITIONAL: Fix minor gaps inline, re-Check, then PASS.
• FAIL: Return to Do — address gaps, re-Check.

Gate Check

The gate-checker agent verifies the requirements spec against shared/gate-templates/requirements-gate.md. If gaps are found, loop back to Do.

PDCA Context

Each phase is a self-contained PDCA loop. This phase's Act feeds directly into the next phase's Plan (flow design receives frozen requirements as input).