taiyi-change

Files (1)

• SKILL.md

SKILL.md (first lines)

# taiyi-change — 变更提案

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

## 框架集成

本阶段使用以下框架：

| 框架 | 用途 | 何时加载 |
|------|------|---------|
| **Harness** | 阶段门禁与推进（`status` → `continue`；legacy：`npx taiyi complete`） | 全程 |
| **OMO** | 作为 workflow 入口，承接 `/taiyi:new` 命令 | 进入时 |
| **Superpowers** | `brainstorming` — 可选，当需求不清晰时加载协助梳理 | 可选 |
| **OpenSpec** | 将 CHANGE.md 同步到 `openspec/changes/<slug>/` | 可选（`taiyi sync-openspec`） |

**`Spec-Kit`** 和 **`GStack`** 在本阶段不涉及。

## 前置门禁（Pre-flight）

### 0.1 架构级变更检测
命中任一 → **反问用户确认**：
1. 改模块结构（新增/拆分/合并目录）
2. 动 ADR（架构决策记录）
3. 改公共契约（API 签名、CLI 参数、DB Schema）
4. 跨服务编排（涉及 2+ 独立服务）

### 0.2 Profile 判定

| Profile | CHANGE.md 要求 |
|---------|---------------|
| `full` | 完整：Motivation + In/Out Scope + Risks + Success Criteria |
| `api/ui` | 同上，Out of scope ≥ 1 条 |
| `lite` | 可省略 Risks 段，其余照常 |
| `micro/spike` | 仅 Motivation + Success Criteria，Out of scope 可选 |
| `nano` | 可跳过本阶段（引擎自动通过） |

### 0.3 前置检查清单
- [ ] slug 命名合理（小写+连字符，如 `fix-login-timeout`）
- [ ] 用户已确认变更目标（不是 AI 自己推断的需求）
- [ ] 不与其他活跃 change 的 Scope 重叠（`taiyi list` 确认）

---

## 步骤

### 工件契约

| 层 | 路径 | 职责 |
|----|------|------|
| **语义真源** | `change.json` | Zod（`src/schemas/change.ts`）— Agent **优先编辑** |
| **生成视图** | `CHANGE.md` | hbs（`src/templates/change.hbs`）— 人读 / PR |
| **流程** | 本 Skill | 门禁、写作纪律、下游衔接 |

**工作流**：编辑 json → `scripts/taiyi-forge.sh render <slug> change` → `status --json --compact` → 用户确认 → `continue --approver "名"`。

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

### json 字段（Zod 摘要）

| 字段 | 要求 |
|------|------|
| `title` | 描述性标题 |
| `motivation` | 谁痛、现状代价、改善指标（具体，不笼统） |
| `scope.includes` | In scope 条目 |
| `scope.excludes` | ≥1 条 Out of scope；关联 change 写 slug |
| `success_criteria` | ≥1 条；`id` + `description`；每条可映射到测试 |
| `risks` | full/api 推荐：`risk` / `probability` / `impact` / `mitigation` |
| `impact_map` | 可选；模块影响面声明 |
| `evidence` | `success_criteria[].is_checked=true` 时必填真跑命令 |

### 1. 编辑 change.json

`/taiyi:new` 已 seed `change.json` + `CHANGE.md`。

**Motivation 好/坏例子**（写入 `motivation`）：

> **好**：当前翻译需人工复制粘贴到 DeepL，每次约 10 分钟。集成 API 后翻译可在 5 秒内完成，消除手动步骤。

> **坏**：需要改进翻译功能。

**Success Criteria**（写入 `success_criteria[]`）：

- 每条可验证：curl / npm test / UI 操作步骤
- 不是「代码写好了」这类不可测试描述

**要求**：

- Motivation 说清「谁痛、现状代价、改善指标」，不笼统
- Out of Scope ≥ 1 条，标注关联 change slug（如有）
- Success Criteria 每条**可直接映射到测试**
- 影响面声明：是否需改 REQUIREMENT / 触及架构（`impact_map` 或 motivation 中说明）
- **不要**写实现细节；**不要**推断用户未确认的范围

### 2. 渲染 CHANGE.md

```bash
scripts/taiyi-forge.sh render <slug> change
```

Zod 校验通过后从 json 重生成 md（去掉 seed 标记）。`continue` 前若 json 已改且 md 仍是 seed/快照态，引擎也会自动 sync。人只改 md 时引擎可 reverse-sync 拉回 json；**显式 render 会覆盖 md**。

### 3. 过关（Harness）

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

Legacy：`npx taiyi complete <slug> change --approver "名"` 仍可用；聊天优先 `/taiyi:continue`。

## 产出

- `.taiyi/changes/<slug>/CHANGE.md`
- `.taiyi/changes/<slug>/change.json`

## 与下游衔接

| 下游 | 需要 |
|------|------|

From Dong90/oh-my-taiyiforge, MIT.

More from Dong90/oh-my-taiyiforge