ironweave 1.1.1 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ironweave",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Agentic skills framework for AI coding agents — orchestrated workflows with adaptive routing, quality gates, and 17 composable skills.",
   "keywords": [
     "agent-skills",

package/skills/requirement-qa/SKILL.md

@@ -1,27 +1,61 @@
 ---
 name: requirement-qa
 description: >-
-  通过多轮 QA 对话引导用户逐步明确需求或技术选型决策。采用“发散→收敛”模式：先开放提问扩展需求边界，再定向追问收敛到可落地的结论。最终输出结构化的需求摘要或技术决策摘要。
+  通过"方向定调 → 增量产出 → 用户 Review → 确认修正"的循环，帮助用户从模糊想法走向完整需求。不同于纯问答模式，本 skill 每轮都产出可 Review 的文档片段到 docs/01-requirement/，用户只需判断"对不对"而非从零表达需求。
   务必在以下场景使用本 skill：用户的需求描述模糊或不完整（如"我想做一个 XX 系统"）、用户不确定技术方案该怎么选、用户要求进行需求分析、需求调研、需求访谈、需求梳理、需求沟通、技术方案讨论、架构讨论，或者用户说"帮我想想还缺什么"、"帮我理一下需求"、"我们聊聊这个项目"。当输入信息不足以直接输出完整文档时，应先进入本 skill 的 QA 流程，而不是凭猜测交付半成品。
 ---
 
 # 需求引导对话（Requirement QA）
 
-本 Skill 通过结构化的多轮对话，帮助用户从模糊想法走向明确、完整、可落地的需求描述或技术决策。它解决的核心问题是：用户脑中有需求，但表达出来的往往只是冰山一角——本 skill 的目标是把水面下的部分也挖出来。
+本 Skill 通过**增量产出 + 用户 Review** 的循环，帮助用户从模糊想法走向明确、完整、可落地的需求描述。
 
-## 核心方法论：发散→收敛
+**核心理念**：用户不需要"说清楚需求"，只需要判断"Agent 产出的内容对不对"。把信息质量的压力从用户转移到 Agent，用户的角色从"回答者"变成"审核者"。
 
-每个话题都经历两个阶段：
+## 产出目标
 
-1. **发散阶段**：开放式提问，探索可能性边界
-   - "还有哪些用户角色会用到这个功能？"
-   - "如果不做这个限制，会发生什么？"
-   - "有没有类似的产品可以参考？"
+每轮 QA 循环直接产出或更新 `docs/01-requirement/` 下的模块化文件：
 
-2. **收敛阶段**：定向追问，锁定具体决策
-   - "在这三个方案中，你倾向哪个？为什么？"
-   - "这个功能的优先级是 P0 还是可以后做？"
-   - "我理解你的意思是 X，对吗？"
+```
+docs/01-requirement/
+├── project-profile.md      ← 项目画像（定位、用户、目标）
+├── feature-scope.md        ← 功能范围（功能列表 + MoSCoW 优先级）
+├── business-rules.md       ← 业务规则（核心规则 + 边界条件）
+├── non-functional.md       ← 非功能要求（性能、安全、合规）
+└── tech-constraints.md     ← 技术约束（技术栈、部署、集成）
+```
+
+这些文件是 `spec-writing` 等后续 skill 的输入。requirement-qa 解决 **What**（做什么），spec-writing 解决 **How**（怎么做到）。
+
+## 核心循环：产出 → Review → 修正
+
+每个模块的处理都遵循同一个三步循环：
+
+### Step 1：用户定方向
+
+用户给出高层级方向或已有信息，可以很简短：
+- "我想做一个在线教育平台"
+- "给内部团队用的项目管理工具"
+- 甚至只是"帮我想想这个系统还缺什么"
+
+Agent 基于已有信息（用户输入 + 仓库工程事实），推断尽可能多的细节。
+
+### Step 2：Agent 产出 + 推荐选项
+
+Agent 做两件事：
+
+1. **直接产出文档片段**：把能推断的内容写成结构化文档，创建或更新到 `docs/01-requirement/` 对应文件
+2. **对不确定的点给出推荐选项**：遵循选项规则（2-5 个选项，标记一个推荐项，最后一个为自由输入）
+
+关键：**先产出再提问**。不要空手来问"你想做什么"——先基于已知信息写一版草稿，再针对草稿中不确定的点提问。
+
+### Step 3：用户 Review + 确认
+
+用户看到的是一个**可 Review 的文档**，不是一堆问题。用户可以：
+- 确认："对，就是这样"→ Agent 进入下一个模块
+- 标注修正："角色描述不对，应该是 XX"→ Agent 更新文件
+- 补充信息："还有一个场景你漏了"→ Agent 补充到文件
+
+Agent 确认用户 Review 结果后，**原地更新**文件（不删除重建），然后进入下一个模块或更深层的追问。
 
 ## 交互方式：优先使用结构化选项
 
@@ -33,10 +67,15 @@ description: >-
 
 详细的选项设计规则、推荐项标记规则、宿主适配方式见 [references/option-rules.md](references/option-rules.md)。
 
-每轮对话结束时做一次**小结确认**，确保双方理解一致后再进入下一个话题。
-
 ## 提问节奏控制
 
+### 先产出再提问
+
+每轮的核心产出是**文档片段**，问题只是文档中不确定点的澄清。比起"问 5 个问题等回答"，更好的做法是：
+- 写一版草稿（80% 推断 + 20% 待确认）
+- 在草稿中用 `<!-- 待确认 -->` 或 **加粗标注** 标记不确定点
+- 针对最关键的 1-3 个不确定点提问
+
 ### 按需产生问题
 
 每轮问多少个问题取决于当前实际需要澄清的未知项：
@@ -58,230 +97,145 @@ description: >-
 
 ### 从工程事实出发
 
-如果当前仓库已经是 Vue 3 项目，不要问"你想用 React 还是 Vue？"——先读事实，再问真正未知的东西。
-
-## 状态跟踪
+如果当前仓库已经是 Vue 3 项目，不要问"你想用 React 还是 Vue？"——先读事实，直接写入 tech-constraints.md，再问真正未知的东西。
 
-每轮问答后，内部维护两个状态：
+## 模块推进流程
 
-- **当前理解**（current understanding）：基于本轮问答后，已经稳定成立的理解
-- **草稿产出**（draft output）：如果此刻就要产出，能交付什么雏形
+### 模块 1：项目画像（project-profile.md）
 
-这两个状态的作用是：让后续轮次围绕"还缺什么"推进，而不是每轮都从零理解。每轮小结时可以展示给用户，让用户看到需求在逐步成形。
+**产出内容**：项目定位、目标用户角色及核心诉求、核心痛点、成功标准、时间约束。
 
-## 对话流程
+**Agent 的做法**：
+1. 读取用户输入 + 扫描仓库（README、package.json、已有文档等）
+2. 基于已知信息，**直接写出** `project-profile.md` 草稿
+3. 对不确定的点提问（如目标用户角色、成功标准）
+4. 用户 Review → 更新文件 → 确认后进入下一模块
 
-### 第一轮：项目画像（必问）
+**产出模板**：
 
-目标：建立项目全貌，5-8 个问题以内完成。
-
-**需求方向的核心问题：**
-- 这个产品/功能是给谁用的？（目标用户角色）
-- 它要解决什么问题？（核心痛点）
-- 用户目前是怎么解决这个问题的？（现状与替代方案）
-- 成功的标准是什么？（可量化的业务目标）
-- 项目的时间约束？（MVP 期限、里程碑）
-
-**技术方向的核心问题：**
-- 团队技术栈现状？（已有项目用了什么、团队熟悉什么）
-- 有没有已定的技术约束？（如必须用内网部署、必须兼容 IE）
-- 预期用户规模？（影响架构选择和性能设计）
-- 部署环境？（云 / 私有化 / 混合）
-- 预算和人力限制？
+```markdown
+# 项目画像：{项目名称}
 
-> **提问原则**：每次最多问 3 个问题。问得太多用户会疲劳，信息质量反而下降。根据用户回答的详细程度调整节奏——回答详细就少问，回答简略就多追问。
+## 项目定位
+{一两句话描述这个产品解决什么问题}
 
-### 第二轮：功能边界探索（发散为主）
+## 目标用户
+| 角色 | 核心诉求 | 使用频率 |
+|------|----------|----------|
+| ... | ... | ... |
 
-目标：穷举功能点、用户场景、边界条件。
+## 核心痛点
+- 用户目前怎么解决这个问题
+- 现有方案的主要不满
 
-**提问策略：**
-- **角色维度**：除了主要用户，还有管理员、审计员、第三方系统吗？
-- **场景维度**：正常流程之外，异常情况怎么处理？批量操作？并发场景？
-- **数据维度**：需要哪些数据输入输出？数据量级？数据生命周期？
-- **集成维度**：需要与哪些外部系统对接？认证方式？数据格式？
-- **非功能维度**：性能要求？安全合规要求？可用性要求？
+## 成功标准
+- {可量化的业务目标}
 
-**避免的反模式：**
-- 不要在这一轮就开始讨论实现方案
-- 不要因为某个功能"很难实现"就引导用户放弃——先记录，后面再讨论优先级
-- 不要一次性把所有问题抛出来——根据用户上一轮的回答动态选择下一个问题
+## 时间约束
+- MVP 期限：
+- 关键里程碑：
+```
 
-### 第三轮：优先级与范围收敛
+### 模块 2：功能范围（feature-scope.md）
 
-目标：从发散出的功能列表中，确定 MVP 范围。
+**产出内容**：功能列表（按 MoSCoW 分类），每个功能附简要验收标准。
 
-**收敛策略：**
-- 按 **MoSCoW** 分类（Must / Should / Could / Won't）
-- 对每个 Must 功能追问验收标准："这个功能做到什么程度算 OK？"
-- 对 Won't 功能确认："这个确定本期不做？以后可能做吗？"
-- 标注依赖关系："功能 A 依赖功能 B，所以 B 也得是 Must"
+**Agent 的做法**：
+1. 基于项目画像，**主动推断**可能的功能列表
+2. 写出 `feature-scope.md` 草稿，按 MoSCoW 分类
+3. 提问："以下功能列表是否完整？优先级是否正确？"
+4. 用户 Review → 增删改 → 更新文件
 
-### 第四轮：技术约束收敛（如果涉及技术选型）
+**产出模板**：
 
-目标：确定关键技术决策点。
+```markdown
+# 功能范围：{项目名称}
 
-**收敛策略：**
-- 把前面收集到的约束汇总成对比表
-- 对每个决策点给出 2-3 个选项 + 利弊分析
-- 让用户做选择，记录选择理由
-- 标注"待验证"的技术风险点
+## Must（MVP 必做）
+- [ ] {功能点} — 验收标准：{简述}
+- [ ] ...
 
-### 第五轮：完整性检查与输出
+## Should（重要但可延后）
+- [ ] ...
 
-目标：确认没有遗漏，输出结构化摘要。
+## Could（锦上添花）
+- [ ] ...
 
-**检查清单：**
-- [ ] 所有用户角色已识别
-- [ ] 核心业务流程已明确
-- [ ] 异常和边界场景已讨论
-- [ ] 优先级已排定（MoSCoW）
-- [ ] 验收标准已定义（至少 Must 项）
-- [ ] 技术约束已记录（如有）
-- [ ] 明确"本期不做"的边界
-- [ ] 与外部系统的集成点已识别
+## Won't（明确不做）
+- [ ] ...
 
-## 对话技巧
+## 功能依赖关系
+- {功能 A} 依赖 {功能 B}
+```
 
-### 应对不同类型的用户
+### 模块 3：业务规则（business-rules.md）
 
-- **话多的用户**：适时打断做小结，"让我确认一下我理解对了……"；帮助聚焦到待讨论的问题上
-- **话少的用户**：提供具体选项而非开放式问题，"你需要的是 A 还是 B？"；用是/否问题确认
-- **犹豫不决的用户**：给出推荐方案 + 理由，"根据你描述的场景，我建议先做 X，原因是……"
-- **过于发散的用户**：温和拉回，"这个想法很好，我先记下来。我们先把核心流程确认完？"
+**产出内容**：核心业务规则、边界条件、异常处理策略。
 
-### 小结模板
+**Agent 的做法**：
+1. 从功能范围中提取隐含的业务规则
+2. **主动推断**常见的边界条件和异常场景
+3. 写出 `business-rules.md`，标注哪些是推断的
+4. 用户 Review → 修正/补充 → 更新文件
 
-每完成一个话题的讨论后，用简洁的结构做一次确认：
+### 模块 4：非功能要求（non-functional.md）
 
-```
-【小结确认】
-话题：用户登录
-已确认：
-- 支持手机号+验证码、邮箱+密码两种方式
-- 暂不做第三方登录（微信、GitHub）
-- 登录失败 5 次锁定 30 分钟
-待确认：
-- 验证码有效期（建议 5 分钟，待确认）
-- 是否需要"记住我"功能
-```
+**产出内容**：性能、安全、可用性、合规等要求。
 
-## 输出格式
+**Agent 的做法**：
+1. 根据项目类型和用户规模，**主动推断**合理的非功能指标
+2. 写出 `non-functional.md`，给出推荐值
+3. 提问：重点确认性能指标和安全合规要求
+4. 用户 Review → 更新文件
 
-对话完成后，输出**结构化需求摘要**或**技术决策摘要**。
+### 模块 5：技术约束（tech-constraints.md）（如涉及技术选型）
 
-### 需求摘要模板
+**产出内容**：技术栈、部署环境、集成点、团队约束。
 
-```markdown
-# 需求摘要：[项目/功能名称]
+**Agent 的做法**：
+1. 扫描仓库获取已有技术栈信息
+2. **直接写入**已确定的事实（不问已经能从代码里看到的东西）
+3. 对需要决策的点给出对比表 + 推荐
+4. 用户 Review → 更新文件
 
-## 项目定位
-[一两句话描述]
+## 对话技巧
 
-## 目标用户
-| 角色 | 核心诉求 |
-|------|----------|
-| ... | ... |
-
-## 功能范围（MoSCoW）
-### Must（MVP 必做）
-- [ ] 功能点 + 验收标准简述
-### Should（重要但可延后）
-- [ ] ...
-### Could（锦上添花）
-- [ ] ...
-### Won't（明确不做）
-- [ ] ...
+### 应对不同类型的用户
 
-## 关键业务规则
-- 规则 1
-- 规则 2
+- **话多的用户**：适时做文档更新，让用户看到信息被结构化了；避免信息在聊天中散落
+- **话少的用户**：多产出、少提问；写出更完整的草稿，让用户只需确认"对/不对"
+- **犹豫不决的用户**：给出推荐方案 + 理由，"根据你描述的场景，我建议先做 X，原因是……"
+- **过于发散的用户**：先记录到文档的 Could/Won't 区域，温和拉回核心流程
 
-## 非功能要求
-- 性能：...
-- 安全：...
+### Review 确认模板
 
-## 待确认事项
-- [ ] ...
+每完成一个模块的文档更新后：
 
-## 技术约束（如有）
-- ...
 ```
+已更新 docs/01-requirement/project-profile.md
 
-### 技术决策摘要模板
-
-```markdown
-# 技术决策摘要：[项目名称]
-
-## 项目约束
-- 团队规模：...
-- 时间线：...
-- 部署环境：...
-
-## 已定决策
-| 决策点 | 选择 | 理由 |
-|--------|------|------|
-| ... | ... | ... |
-
-## 待验证风险
-- [ ] ...
+待确认点：
+1. 目标用户是否只有"学生"和"教师"两个角色？
+2. 成功标准中"日活 1000"是否合理？
 
-## 版本约束
-- Node.js: ...
-- pnpm: ...
+请 Review 文件内容，告诉我哪里需要修正。确认后我进入下一模块（功能范围）。
 ```
 
 ## 执行方式
 
 1. **判断进入条件**：用户的输入信息不足以直接输出完整文档时，进入 QA 流程
-2. **按轮次推进**：不需要严格按五轮走，根据实际情况灵活调整；信息够了就提前结束
-3. **每轮小结**：确保双方理解一致后再继续
-4. **适时退出**：当检查清单大部分打勾、用户表示"差不多了"时，输出结构化摘要
-5. **输出摘要**：摘要输出后，提示用户可以用该摘要生成正式文档
+2. **从项目画像开始**：无论信息多少，先产出 project-profile.md 草稿
+3. **按模块推进**：每个模块走"产出 → Review → 修正"循环；信息够了就跳过某些模块
+4. **原地更新**：每次修正都更新同一个文件，不创建新文件
+5. **适时退出**：当所有 Must 模块完成 Review，用户表示满意时，输出完成总结
+6. **衔接后续**：提示用户可以用 `docs/01-requirement/` 的产出进入 spec-writing 生成详细需求文档
 
 ## 完成信号
 
-默认只有以下情况可以结束 QA 并输出摘要：
+默认只有以下情况可以结束 QA：
 - 用户明确说"开始产出""可以写文档了""按这个做"等
-- 检查清单中所有 Must 项已确认
+- project-profile.md 和 feature-scope.md 至少已完成 Review
 
-如果用户说"继续问""先别开始"，优先视为继续澄清。即使用户要求立即结束但信息不完整，在输出摘要中**显式列出假设**。
+如果用户说"继续问""先别开始"，优先视为继续澄清。即使用户要求立即结束但信息不完整，在文档中**显式列出假设**，标注为"未经用户确认，基于推断"。
 
 完整的信号列表和最低结束标准见 [references/completion-signals.md](references/completion-signals.md)。
-
-## 文档持久化
-
-每轮问答应落盘到 Markdown 文件，不依赖模型记忆。使用 `scripts/qa_session.py` 管理会话文档：
-
-```bash
-# 开始新会话
-python3 skills/requirement-qa/scripts/qa_session.py start \
-  --topic "用户登录功能" \
-  --initial-request "我要做一个登录功能"
-
-# 记录每轮问答
-python3 skills/requirement-qa/scripts/qa_session.py append-turn \
-  --doc-path "<doc_path>" \
-  --question "支持哪些登录方式？" \
-  --answer "手机号+验证码、邮箱+密码" \
-  --confirmed "支持手机号+验证码" \
-  --confirmed "支持邮箱+密码" \
-  --open-item "是否需要第三方登录" \
-  --current-understanding "核心登录方式已确认"
-
-# 结束会话
-python3 skills/requirement-qa/scripts/qa_session.py finalize \
-  --doc-path "<doc_path>" \
-  --final-summary "登录功能需求已收敛" \
-  --deliverable "需求摘要文档"
-```
-
-文档存放在 `docs/qa/` 目录下，每个会话一个文件。
-
-## 资源
-
-| 路径 | 说明 |
-|------|------|
-| `references/option-rules.md` | 选项设计规则、推荐项标记规则、宿主适配方式 |
-| `references/completion-signals.md` | 完成信号列表、继续意图保护、最低结束标准 |
-| `scripts/qa_session.py` | QA 会话文档的创建、追加、结束 |

package/skills-en/requirement-qa/SKILL.md

@@ -1,287 +1,241 @@
 ---
 name: requirement-qa
 description: >-
-  Guide users to progressively clarify requirements or technical decisions through multi-round QA dialog. Uses a "diverge then converge" pattern: first ask open questions to expand requirement boundaries, then ask focused follow-ups to converge on actionable conclusions. Outputs structured requirement summaries or technical decision summaries.
-  Use this skill when: the user's requirement description is vague or incomplete (e.g. "I want to build an XX system"), the user is unsure about technical approach selection, the user requests requirement analysis, requirement research, requirement interviews, requirement review, requirement communication, technical proposal discussion, architecture discussion, or says "help me think about what's missing", "help me sort out requirements", "let's discuss this project". When input is insufficient to produce a complete document, enter this skill's QA flow first rather than delivering half-baked guesswork.
+  Guides users from vague ideas to complete requirements through a "Set Direction → Incremental Output → User Review → Confirm/Correct" loop. Unlike pure Q&A mode, this skill produces reviewable document fragments to docs/01-requirement/ each round — users only need to judge "is this right?" rather than articulate requirements from scratch.
+  Use this skill when: user's requirements are vague or incomplete (e.g., "I want to build a XX system"), user is unsure about technical choices, user requests requirement analysis/review/interview/brainstorming/architecture discussion, or says "help me think about what's missing", "help me sort out the requirements", "let's talk about this project". When input is insufficient for a complete document, enter this skill's QA flow rather than delivering guesswork.
 ---
 
-# Requirement QA Dialog
+# Requirement QA
 
-This Skill helps users move from fuzzy ideas to clear, complete, actionable requirement descriptions or technical decisions through structured multi-round dialog. The core problem it solves: users have requirements in their heads, but what they express is often just the tip of the iceberg — this skill's goal is to surface what's beneath.
+This skill guides users from vague ideas to clear, complete, actionable requirements through **incremental output + user review** loops.
 
-## Core Methodology: Diverge then Converge
+**Core principle**: Users don't need to "articulate requirements clearly" — they just need to judge "is what the Agent produced correct?" This shifts the information quality burden from user to Agent, changing the user's role from "answerer" to "reviewer."
 
-Each topic goes through two phases:
+## Output Target
 
-1. **Diverge Phase**: Open-ended questions to explore possibility boundaries
-   - "What other user roles will use this feature?"
-   - "What happens if we don't impose this restriction?"
-   - "Are there similar products we can reference?"
+Each QA loop directly creates or updates modular files under `docs/01-requirement/`:
 
-2. **Converge Phase**: Directed follow-ups to lock in specific decisions
-   - "Among these three options, which do you prefer? Why?"
-   - "Is this feature P0 or can it be deferred?"
-   - "I understand you mean X — is that correct?"
-
-## Interaction Style: Prefer Structured Options
-
-Prefer using the structured questioning capabilities provided by the current Agent's host editor, rather than system-level dialogs. Fall back to plain chat messages only if the host completely lacks structured questioning support. The clarification logic is the same across hosts — only the UI presentation differs; no logic branching is allowed.
-
-Core rules:
-- Each question has **2-5 options**, **must mark exactly one recommended option** (with reasoning), **last option is always free-form input**
-- Recommendation basis: Engineering facts > contextual inference > industry conventions > safety-side preference
-
-For detailed option design rules, recommended option marking rules, and host adaptation methods, see [references/option-rules.md](references/option-rules.md).
+```
+docs/01-requirement/
+├── project-profile.md      ← Project profile (positioning, users, goals)
+├── feature-scope.md        ← Feature scope (feature list + MoSCoW priorities)
+├── business-rules.md       ← Business rules (core rules + edge cases)
+├── non-functional.md       ← Non-functional requirements (performance, security, compliance)
+└── tech-constraints.md     ← Technical constraints (tech stack, deployment, integrations)
+```
 
-At the end of each dialog round, do a **brief summary confirmation** to ensure mutual understanding before moving to the next topic.
+These files serve as input for subsequent skills like `spec-writing`. requirement-qa addresses **What** (what to build), spec-writing addresses **How** (how to achieve it).
 
-## Questioning Rhythm Control
+## Core Loop: Output → Review → Correct
 
-### Generate Questions On Demand
+Every module follows the same three-step loop:
 
-How many questions per round depends on the actual unknowns to clarify:
+### Step 1: User Sets Direction
 
-- Only one key unknown? Ask just one question
-- Multiple **independent** unknowns can be asked together in one round to reduce back-and-forth
-- Multiple **dependent** unknowns must be split across rounds — later questions depend on earlier answers
+User provides high-level direction or existing information — can be very brief:
+- "I want to build an online education platform"
+- "An internal project management tool for the team"
+- Or even just "help me think about what this system is missing"
 
-**Bad example**: Forcing dependent questions into one round — "Are you building Web or desktop? Which browsers to support?" (browser question depends on the "Web" premise)
+The Agent infers as many details as possible based on available information (user input + repository engineering facts).
 
-**Correct approach**: First ask "What is the final product form?", then ask specific constraints based on the answer.
+### Step 2: Agent Outputs + Recommends Options
 
-### High-Value Questions First
+The Agent does two things:
 
-Prioritize questions that can change the execution path:
+1. **Directly produces document fragments**: Writes inferrable content as structured documents, creates or updates the corresponding file in `docs/01-requirement/`
+2. **Provides recommended options for uncertain points**: Following option rules (2-5 options, one marked as recommended, last one is free input)
 
-- **Ask first**: What to build, for whom, to what extent, scope boundaries
-- **Ask later**: What technology, what style, what UI preferences
+Key: **Output first, then ask**. Don't come empty-handed asking "what do you want to build?" — first write a draft based on known information, then ask about uncertain points in the draft.
 
-### Start from Engineering Facts
+### Step 3: User Review + Confirmation
 
-If the current repo is already a Vue 3 project, don't ask "Do you want React or Vue?" — read facts first, then ask about genuinely unknown things.
+What the user sees is a **reviewable document**, not a pile of questions. Users can:
+- Confirm: "Yes, that's right" → Agent moves to next module
+- Mark corrections: "The role description is wrong, it should be XX" → Agent updates the file
+- Add information: "There's a scenario you missed" → Agent adds to the file
 
-## State Tracking
+After confirming user review results, the Agent **updates the file in place** (no delete-and-recreate), then moves to the next module or deeper follow-ups.
 
-After each Q&A round, maintain two internal states:
+## Interaction: Prefer Structured Options
 
-- **Current understanding**: What has been stably established based on this round's Q&A
-- **Draft output**: What deliverable draft could be produced if we had to output right now
+Prefer the structured questioning capability provided by the current Agent host editor, not system-level popups. Only fall back to plain chat messages if the host completely lacks structured questioning support. There is only one clarification logic — different hosts only differ in UI presentation, no logic forking allowed.
 
-These states ensure subsequent rounds focus on "what's still missing" rather than re-understanding from scratch each round. They can be shown to the user during summaries so they can see requirements taking shape.
+Core rules:
+- Each question has **2-5 options**, **must mark exactly one as recommended** (with rationale), **last option is always free input**
+- Recommendation basis: Engineering facts > Context inference > Industry conventions > Safety-side preference
 
-## Dialog Flow
+For detailed option design rules, recommendation marking rules, and host adaptation, see [references/option-rules.md](references/option-rules.md).
 
-### Round 1: Project Profile (Required)
+## Question Pacing
 
-Goal: Establish the full project picture within 5-8 questions.
+### Output First, Then Ask
 
-**Requirement-oriented core questions:**
-- Who is this product/feature for? (target user roles)
-- What problem does it solve? (core pain points)
-- How do users currently solve this problem? (status quo and alternatives)
-- What does success look like? (quantifiable business goals)
-- Project timeline constraints? (MVP deadline, milestones)
+The core output of each round is a **document fragment** — questions only clarify uncertain points in the document. Instead of "ask 5 questions and wait for answers", the better approach is:
+- Write a draft (80% inferred + 20% to be confirmed)
+- Mark uncertain points in the draft with `<!-- to be confirmed -->` or **bold annotations**
+- Ask about the 1-3 most critical uncertain points
 
-**Technology-oriented core questions:**
-- Current team tech stack? (existing projects, team expertise)
-- Any predetermined technical constraints? (e.g., must deploy on-premise, must support IE)
-- Expected user scale? (impacts architecture and performance design)
-- Deployment environment? (cloud / private / hybrid)
-- Budget and staffing limitations?
+### Generate Questions as Needed
 
-> **Questioning principle**: Ask at most 3 questions per round. Too many causes fatigue, degrading information quality. Adjust rhythm based on answer detail level — detailed answers mean fewer questions needed; brief answers mean more follow-up.
+How many questions per round depends on actual unknowns that need clarification:
 
-### Round 2: Feature Boundary Exploration (Diverge-heavy)
+- Only one key unknown → ask only one question
+- Multiple **independent** unknowns can be asked together in one round to reduce round-trips
+- Multiple **dependent** unknowns must be split across rounds — later questions depend on earlier answers
 
-Goal: Enumerate feature points, user scenarios, boundary conditions.
+**Anti-pattern**: Forcing dependent questions into one round — "Are you building for web or desktop? Which browsers to support?" (browsers depend on "web" as a prerequisite)
 
-**Questioning strategies:**
-- **Role dimension**: Beyond primary users, are there admins, auditors, third-party systems?
-- **Scenario dimension**: Beyond normal flow, how to handle exceptions? Batch operations? Concurrent scenarios?
-- **Data dimension**: What data inputs/outputs? Data volume? Data lifecycle?
-- **Integration dimension**: Which external systems to connect with? Auth methods? Data formats?
-- **Non-functional dimension**: Performance requirements? Security/compliance requirements? Availability requirements?
+**Correct approach**: First ask "what's the final product form", then ask specific constraints based on the answer.
 
-**Anti-patterns to avoid:**
-- Don't start discussing implementation details in this round
-- Don't steer users away from features just because they're "hard to implement" — record first, discuss priority later
-- Don't dump all questions at once — dynamically select next questions based on previous answers
+### High-Value Questions First
 
-### Round 3: Priority and Scope Convergence
+Prioritize questions that change the execution path:
 
-Goal: From the diverged feature list, determine MVP scope.
+- **Ask first**: What to build, for whom, to what extent, scope boundaries
+- **Ask later**: Which technology, what style, what UI preferences
 
-**Convergence strategies:**
-- Classify by **MoSCoW** (Must / Should / Could / Won't)
-- For each Must feature, follow up with acceptance criteria: "What level of completion counts as OK?"
-- For Won't features, confirm: "Definitely not this phase? Possibly later?"
-- Mark dependencies: "Feature A depends on Feature B, so B must also be Must"
+### Start from Engineering Facts
 
-### Round 4: Technical Constraint Convergence (if tech decisions involved)
+If the current repository is already a Vue 3 project, don't ask "Do you want React or Vue?" — read facts first, write them directly into tech-constraints.md, then ask about genuinely unknown things.
 
-Goal: Determine key technical decision points.
+## Module Progression
 
-**Convergence strategies:**
-- Aggregate collected constraints into comparison tables
-- For each decision point, present 2-3 options + pros/cons analysis
-- Let user choose, record the reasoning
-- Mark "to-be-validated" technical risks
+### Module 1: Project Profile (project-profile.md)
 
-### Round 5: Completeness Check and Output
+**Output content**: Project positioning, target user roles and core needs, core pain points, success criteria, time constraints.
 
-Goal: Confirm nothing is missed, output structured summary.
+**Agent's approach**:
+1. Read user input + scan repository (README, package.json, existing docs, etc.)
+2. Based on known information, **directly write** a `project-profile.md` draft
+3. Ask about uncertain points (e.g., target user roles, success criteria)
+4. User reviews → update file → confirm and move to next module
 
-**Checklist:**
-- [ ] All user roles identified
-- [ ] Core business flows clarified
-- [ ] Exception and boundary scenarios discussed
-- [ ] Priorities ranked (MoSCoW)
-- [ ] Acceptance criteria defined (at least for Must items)
-- [ ] Technical constraints documented (if any)
-- [ ] "Not doing this phase" boundaries explicit
-- [ ] Integration points with external systems identified
+**Output template**:
 
-## Dialog Techniques
+```markdown
+# Project Profile: {Project Name}
 
-### Handling Different User Types
+## Positioning
+{One or two sentences describing what problem this product solves}
 
-- **Verbose users**: Interrupt with timely summaries — "Let me confirm I understood correctly..."; help focus on pending questions
-- **Terse users**: Provide specific options instead of open-ended questions — "Do you need A or B?"; use yes/no questions for confirmation
-- **Indecisive users**: Give recommended approaches + reasoning — "Based on your scenario, I suggest doing X first because..."
-- **Over-divergent users**: Gently redirect — "Great idea, I'll note it down. Let's finish confirming the core flow first?"
+## Target Users
+| Role | Core Need | Usage Frequency |
+|------|-----------|-----------------|
+| ... | ... | ... |
 
-### Summary Template
+## Core Pain Points
+- How users currently solve this problem
+- Main dissatisfaction with existing solutions
 
-After completing discussion of each topic, do a concise structured confirmation:
+## Success Criteria
+- {Quantifiable business objectives}
 
+## Time Constraints
+- MVP deadline:
+- Key milestones:
 ```
-[Summary Confirmation]
-Topic: User Login
-Confirmed:
-- Support phone number+SMS code and email+password methods
-- No third-party login for now (WeChat, GitHub)
-- Lock account for 30 minutes after 5 failed attempts
-Pending:
-- SMS code validity period (suggest 5 minutes, TBC)
-- Whether "remember me" feature is needed
-```
 
-## Output Format
+### Module 2: Feature Scope (feature-scope.md)
+
+**Output content**: Feature list (categorized by MoSCoW), each with brief acceptance criteria.
 
-After dialog completion, output a **structured requirement summary** or **technical decision summary**.
+**Agent's approach**:
+1. Based on project profile, **proactively infer** likely feature list
+2. Write `feature-scope.md` draft, categorized by MoSCoW
+3. Ask: "Is this feature list complete? Are priorities correct?"
+4. User reviews → add/remove/modify → update file
 
-### Requirement Summary Template
+**Output template**:
 
 ```markdown
-# Requirement Summary: [Project/Feature Name]
+# Feature Scope: {Project Name}
 
-## Project Positioning
-[One or two sentence description]
+## Must (MVP Essential)
+- [ ] {Feature} — Acceptance criteria: {brief description}
+- [ ] ...
 
-## Target Users
-| Role | Core Need |
-|------|----------|
-| ... | ... |
-
-## Feature Scope (MoSCoW)
-### Must (MVP Essentials)
-- [ ] Feature + brief acceptance criteria
-### Should (Important but Deferrable)
+## Should (Important but Deferrable)
 - [ ] ...
-### Could (Nice-to-have)
+
+## Could (Nice to Have)
 - [ ] ...
-### Won't (Explicitly Out of Scope)
+
+## Won't (Explicitly Excluded)
 - [ ] ...
 
-## Key Business Rules
-- Rule 1
-- Rule 2
+## Feature Dependencies
+- {Feature A} depends on {Feature B}
+```
 
-## Non-Functional Requirements
-- Performance: ...
-- Security: ...
+### Module 3: Business Rules (business-rules.md)
 
-## Pending Items
-- [ ] ...
+**Output content**: Core business rules, edge cases, exception handling strategies.
 
-## Technical Constraints (if any)
-- ...
-```
+**Agent's approach**:
+1. Extract implicit business rules from feature scope
+2. **Proactively infer** common edge cases and exception scenarios
+3. Write `business-rules.md`, annotating which items are inferred
+4. User reviews → correct/supplement → update file
 
-### Technical Decision Summary Template
+### Module 4: Non-Functional Requirements (non-functional.md)
 
-```markdown
-# Technical Decision Summary: [Project Name]
+**Output content**: Performance, security, availability, compliance requirements.
 
-## Project Constraints
-- Team size: ...
-- Timeline: ...
-- Deployment environment: ...
+**Agent's approach**:
+1. Based on project type and user scale, **proactively infer** reasonable non-functional metrics
+2. Write `non-functional.md` with recommended values
+3. Ask: Focus on confirming performance metrics and security/compliance requirements
+4. User reviews → update file
 
-## Confirmed Decisions
-| Decision Point | Choice | Reasoning |
-|--------|------|------|
-| ... | ... | ... |
+### Module 5: Technical Constraints (tech-constraints.md) (if applicable)
 
-## Risks to Validate
-- [ ] ...
+**Output content**: Tech stack, deployment environment, integration points, team constraints.
 
-## Version Constraints
-- Node.js: ...
-- pnpm: ...
-```
+**Agent's approach**:
+1. Scan repository for existing tech stack information
+2. **Directly write** confirmed facts (don't ask about things already visible in code)
+3. For decision points, provide comparison tables + recommendations
+4. User reviews → update file
 
-## Execution Method
+## Conversation Techniques
 
-1. **Check entry conditions**: Enter QA flow when user input is insufficient to produce a complete document
-2. **Progress by rounds**: No need to strictly follow five rounds — adjust flexibly based on actual needs; end early when enough info is gathered
-3. **Summarize each round**: Ensure mutual understanding before continuing
-4. **Exit when ready**: When most checklist items are checked or user says "that's about it", output structured summary
-5. **Output summary**: After summary output, prompt user that they can use it to generate formal documents
+### Adapting to Different User Types
 
-## Completion Signals
+- **Talkative users**: Promptly update documents so users see information being structured; avoid information scattering in chat
+- **Quiet users**: More output, fewer questions; write more complete drafts so users only need to confirm "right/wrong"
+- **Indecisive users**: Provide recommended solution + rationale: "Based on your scenario, I suggest doing X first because..."
+- **Divergent users**: Record ideas to the Could/Won't section of documents, gently guide back to core flow
 
-By default, QA ends and summary is output only when:
-- User explicitly says "start producing", "you can write the doc now", "go ahead with this", etc.
-- All Must items in the checklist are confirmed
+### Review Confirmation Template
 
-If user says "keep asking" or "don't start yet", treat as continuing clarification. Even if user demands immediate end but info is incomplete, **explicitly list assumptions** in the output summary.
+After completing a module's document update:
 
-For the complete signal list and minimum exit criteria, see [references/completion-signals.md](references/completion-signals.md).
+```
+Updated docs/01-requirement/project-profile.md
+
+Points to confirm:
+1. Are the target users limited to "students" and "teachers"?
+2. Is "1000 DAU" a reasonable success criterion?
 
-## Document Persistence
-
-Each Q&A round should be persisted to a Markdown file, not relying on model memory. Use `scripts/qa_session.py` to manage session documents:
-
-```bash
-# Start new session
-python3 skills/requirement-qa/scripts/qa_session.py start \
-  --topic "User Login Feature" \
-  --initial-request "I need a login feature"
-
-# Record each round
-python3 skills/requirement-qa/scripts/qa_session.py append-turn \
-  --doc-path "<doc_path>" \
-  --question "Which login methods to support?" \
-  --answer "Phone+SMS code, email+password" \
-  --confirmed "Support phone+SMS code" \
-  --confirmed "Support email+password" \
-  --open-item "Whether third-party login is needed" \
-  --current-understanding "Core login methods confirmed"
-
-# Finalize session
-python3 skills/requirement-qa/scripts/qa_session.py finalize \
-  --doc-path "<doc_path>" \
-  --final-summary "Login feature requirements converged" \
-  --deliverable "Requirement summary document"
+Please review the file content and let me know what needs correction. After confirmation, I'll move to the next module (feature scope).
 ```
 
-Documents are stored in the `docs/qa/` directory, one file per session.
+## Execution
 
-## Resources
+1. **Entry condition**: When user input is insufficient for a complete document, enter QA flow
+2. **Start with project profile**: Regardless of information volume, first produce a project-profile.md draft
+3. **Progress by module**: Each module goes through "output → review → correct" loop; skip modules if information is sufficient
+4. **Update in place**: Each correction updates the same file, no new files created
+5. **Exit when ready**: When all Must modules are reviewed and user is satisfied, output completion summary
+6. **Handoff**: Prompt user that `docs/01-requirement/` output can feed into spec-writing for detailed requirement documents
 
-| Path | Description |
-|------|------|
-| `references/option-rules.md` | Option design rules, recommended option marking rules, host adaptation |
-| `references/completion-signals.md` | Completion signal list, continue-intent protection, minimum exit criteria |
-| `scripts/qa_session.py` | QA session document creation, appending, and finalization |
+## Completion Signals
+
+QA can only end in these situations by default:
+- User explicitly says "start output", "ready to write docs", "go with this", etc.
+- project-profile.md and feature-scope.md have at least completed review
+
+If user says "keep asking" or "don't start yet", treat as continue clarification. Even if user insists on ending immediately but information is incomplete, **explicitly list assumptions** in documents, annotated as "Not confirmed by user, based on inference."
+
+For the complete signal list and minimum exit criteria, see [references/completion-signals.md](references/completion-signals.md).