taiyi-requirement

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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 格式：

From Dong90/oh-my-taiyiforge, MIT.

More from Dong90/oh-my-taiyiforge