/taiyi-requirement

name: taiyi-requirement
description: TaiyiForge 第2阶段 — 需求分析，REQUIREMENT.md。四端通用。
paradigm: Partner

taiyi-requirement — 需求分析

> 进入本阶段前请优先读 `.taiyi/changes/<slug>/PHASE-CONTEXT.md`（~500 tokens），不要全量加载上游工件。

框架集成

本阶段使用以下框架：

| 框架 | 用途 | 何时加载 | |------|------|---------| | **Harness** | 阶段门禁与推进（`status` → `continue`；legacy：`npx taiyi complete`） | 全程 | | **OpenSpec** | 将 REQUIREMENT.md 同步到 openspec 格式 | 可选 |

**Superpowers / GStack / Spec-Kit / OMO** 在本阶段不涉及。

前置门禁（Pre-flight）

0.1 上游检查

• change 阶段已过关（`engineTruth.completedPhases` 含 `change` 或 `currentPhase` 已推进）
• 无跨 change 的 AC 冲突（`taiyi list` 检查其他活跃 change 的 scope）

0.2 Profile 判定

| Profile | REQUIREMENT.md 要求 | |---------|-------------------| | `full` | 完整：User Stories + AC(Given/When/Then) + 域语言 + Traceability | | `api/ui` | User Stories + AC，域语言可选 | | `lite` | 仅 AC 列表，可省 User Stories | | `micro/spike` | 可跳过本阶段 | | `nano` | 跳过 |

0.3 触发者检查

每个 FR 必须声明触发点：

• 每个 FR 必须填写 `trigger`（谁调用、什么时机）
• `trigger` 指向的 `caller_module` 不在本 change scope 中 → 填 `blocked_by` 标注依赖
• `blocked_by` 非空 → 本阶段不能过关，等依赖 change 完成后再继续

"functional_requirements": [{
  "module": "orchestrator",
  "items": [{
    "id": "FR-T01",
    "description": "track(slug,role,amount) 更新 pipeline.json tokenBudget.used",
    "trigger": "executor.dispatch() 每次调用后",
    "caller_module": "packages/orchestrator/src/executor.ts",
    "blocked_by": "M4-executor"
  }]
}]

`blocked_by` 非空时引擎会在 status 中报 blocker，阻止进入 design 阶段。

0.4 前置检查清单

• [ ] change 阶段已过关
• [ ] 理解 CHANGE Scope 和 Out of Scope 边界
• [ ] 每个 FR 有 trigger（谁调用、什么时机）；caller 不在 scope 时填 blocked_by

---

步骤

工件契约

| 层 | 路径 | 职责 | |----|------|------| | **语义真源** | `requirement.json` | Zod（`src/schemas/requirement.ts`） | | **生成视图** | `REQUIREMENT.md` | hbs（`src/templates/requirement.hbs`） | | **流程** | 本 Skill | US / AC / 域语言 / Traceability 纪律 |

**工作流**：编辑 json → `scripts/taiyi-forge.sh render <slug> requirement` → `status` → `continue`。

详见 [`docs/taiyi/artifact-contract.md`](../../docs/taiyi/artifact-contract.md)。

json 字段（Zod 摘要）

| 字段 | 要求 | |------|------| | `title` | 一句话概括核心需求 | | `features` | 核心功能点列表 | | `scope_out` | 明确排除项（对齐 CHANGE `scope.excludes`） | | `acceptance_criteria` | ≥1 条；`id` + `description`；Given/When/Then 写在 description | | `functional_requirements` | 可选；按模块组织 | | `non_functional` | 可选；performance / security / availability | | `error_rescue_map` | 可选；错误 → 用户可见 → 恢复 | | `shadow_paths` / `non_happy_path_cases` | 可选；边界与非快乐路径 | | `dependencies` | 可选；外部依赖与风险 | | `evidence` | AC 标 `is_checked=true` 时必填 |

写作指引（填入 json，render 生成 REQUIREMENT.md）

1. 拆 User Stories

从 CHANGE.md Motivation + Scope 拆出用户故事。每条用标准格式：

## US-{N}: {标题}

As a **{角色}**
I want **{功能}**
So that **{价值}**

### Acceptance Criteria

**AC-{N}.{M}**: {描述}
Given {前置条件}
  When {操作}
  Then {预期结果}

**要求**：

• 每条 US 必须能追踪到 CHANGE.md 的 Motivation 或 Scope
• US 不写技术方案（不在需求层说"用 Redis"）

2. 写 AC（Acceptance Criteria）

每条 AC 使用 Given/When/Then 格式：

**AC-1.1**: 用户输入有效邮箱能通过验证
Given 用户输入了 "user@example.com"
  When 系统校验邮箱格式
  Then 返回验证通过

**好 AC**：

• 可量化（"返回 200"、"耗时 < 200ms"、"响应体包含字段 X"）
• 包含边界值（空输入、超长字符串、特殊字符、分页极限）
• 描述外部可见行为，不涉及内部实现
• 包含中间状态（Loading → Success / Error）
• 错误路径有明确可观测结果（HTTP 4xx / toast 提示 / 按钮置灰）

**好 AC 例子**：

• ✅ "用户点击重置后，表单所有字段恢复到初始空值状态"
• ✅ "搜索耗时 > 5s 时，页面展示 '搜索超时' 提示，搜索框不清空可重试"
• ✅ "删除确认弹窗点击取消，关闭弹窗且列表不刷新"
• ✅ "页面数据加载中，表格区域显示骨架屏，不显示空表头"
• ✅ "连续两次提交相同表单，第二次收到 409 Conflict，页面不跳转"
• ✅ "翻到最后一页时，加载更多按钮变为灰色文字'已加载全部'"

**坏 AC**：

• ❌ "校验通过"（不可验证——什么校验？校验什么？）
• ❌ "使用正则表达式验证"（在描述实现，不是行为）
• ❌ "应该正常工作"（不可测量——什么叫正常）
• ❌ "系统处理请求"（太泛，没有可观测结果）
• ❌ "调用翻译 API"（在描述内部调用链，不是用户可见行为）
• ❌ "不做过多处理"（模糊，无法写断言）
• ❌ "程序运行稳定"（无法在一次测试中验证）
• ❌ "修复以前的问题"（引用非本次 scope）
• ❌ "加好注释"（代码规范，不是 AC）

3. 提取域语言

从 US + AC 中提取关键术语，写入 REQUIREMENT.md preamble：

## 域语言

| 术语 | 定义 | 使用场景 |
|------|------|---------|
| TranslationRequest | 用户提交的翻译请求 | US-1, US-2 |
| TranslationDirection | 翻译方向枚举（dev→product 等） | US-3 |

**要求**：

• 域语言是代码中一致的命名来源
• 跨 change 的术语应保持一致（检查已有 CONTEXT.md）

4. Traceability

建立 AC ↔ CHANGE Success Criteria ↔ 验证方式的追踪表：

## Traceability

| AC | CHANGE SC | 验证方式 |
|----|-----------|---------|
| AC-1.1 | SC-1（API 返回 200） | curl -s -w '%{http_code}' POST /api/translate |
| AC-2.1 | SC-2（SSE 流式响应） | curl -N -s POST /api/translate/stream |

**要求**：

• 每条 CHANGE Success Criteria 至少对应 1 条 AC
• 验证方式必须是可执行命令（不是"写测试"）

---

过关（Harness）

1. 逐项检查 `## 质量自检`；有未通过项则不要过关。 2. 预检：`scripts/taiyi-forge.sh status <slug> --json --compact` — 解析 `engineTruth`（`qualityReady` / `blockers`）。 3. 用户确认后过关：`scripts/taiyi-forge.sh continue <slug>`。 4. 过关后再 `status --json --compact`，读 `engineTruth`；若 `currentPhase` 已变为 `design`，切换到 taiyi-design Skill 并通知用户。

Legacy：`npx taiyi complete <slug> requirement` 仍可用；聊天优先 `/taiyi:continue`。

产出

• `.taiyi/changes/<slug>/REQUIREMENT.md`
• `.taiyi/changes/<slug>/requirement.json`

与下游衔接

| 下游 | 需要 | |------|------| | `taiyi-design` | User Stories → 方案必须覆盖的功能；AC → 设计决策的验收标准；域语言 → 代码中一致的术语 | | `taiyi-test` | AC（Given/When/Then）→ 第 1 轮功能测试的用例来源；Traceability → 测试覆盖范围 |

异常处理

| 场景 | 处理 | |------|------| | `continue` 被拒 | 检查 Traceability 是否缺失（AC↔CHANGE SC）、AC 是否可量化。修复后 status 再 continue。**最多 1 次自动重试** | | CHANGE 未过关（phase guard） | 告知用户 change 阶段未完成，无法继续 | | US 与已有 change 的 US 重叠 | 标注引用关系，避免重复或冲突的 AC | | 域语言与已有 CONTEXT.md 冲突 | 使用已有术语，**不要另起一套命名**。记录到 Traceability | | 误过关本阶段或后续 | `scripts/taiyi-forge.sh undo <slug> requirement`（回滚本阶段及之后已完成阶段） |

<fatal_constraints>

• NEVER write vague AC (no quantifiable criteria).
• NEVER write technical solutions in requirement.json / rendered REQUIREMENT.md.
• NEVER skip Traceability (AC↔CHANGE SC↔verification method).
• NEVER invent User Stories that don't trace back to CHANGE.md Motivation or Scope.
• NEVER use domain language that contradicts existing CONTEXT.md.

</fatal_constraints>

质量自检

• [ ] 前置门禁已通过（0.1–0.3）
• [ ] 每条 User Story 有 As a / I want / So that
• [ ] 每条 AC 用 Given/When/Then 格式
• [ ] Traceability 完整（AC ↔ CHANGE S