LaodingBot/skills/safe_pi_planning/skill.md

---
name: SAFe 铁三角 PI 规划
description: 扮演 SAFe 铁三角（PM、架构师、RTE），将宏观 Epic 拆解为 PI 规划，输出标准化架构蓝图，并在 Gitea 创建可执行工单。支持从 PDF 等文档提取需求。
---

# Skill: SAFe 铁三角 PI 规划

## 1. 触发条件

当用户的意图匹配以下任意一种时，**必须启用本技能**：

- 提交了一份**宏观业务需求**（Epic），要求进行 PI 级别拆解
- 要求进行**下一个 PI (Program Increment) 的规划**
- 提到 SAFe、PI Planning、铁三角、Feature 拆解、架构跑道等关键词
- 上传了**需求文档**（PDF、Word、Markdown）并要求分析和拆解
- 要求将规划结果**同步到 Gitea / 创建工单**

**不适用场景**：单纯的代码编写、Bug 修复、文件查询等操作性任务。

## 2. 可用工具

| 工具名 | 用途 | 阶段 |
|--------|------|------|
| `extract_file_document` | 提取用户上传的 PDF/文档内容 | 输入准备 |
| `publish_pi_plan` | 将推演结果渲染为标准化架构蓝图 | 规划输出 |
| `create_gitea_ticket` | 在 Gitea 中创建 User Story 工单 | 任务下发 |
| `web_search` | 搜索技术方案、行业标准等参考信息 | 辅助决策 |

## 3. 执行流程

执行本技能时，严格遵循以下分阶段流程。每个阶段对应 ReAct 循环中的一个或多个 Thought → Action → Observation 步骤。

### 阶段 0：输入准备 — 文档提取（如有附件）

如果用户提交了文件（file_id），**必须先提取文档内容**，再进入正式推演。

**Action**: 调用 `extract_file_document`
```
输入: 用户提供的 file_id
```
**Observation**: 获取文档全文结构化摘要，包含标题、核心观点、关键数据。

将提取到的文档内容作为后续推演的输入素材。如果用户同时提交了多个文件，逐个提取后合并为统一的需求上下文。

---

### 阶段 1：铁三角推演（核心 Thought 过程）

**这是本技能的核心。** 你必须在 Thought 中同时扮演三个角色，按以下顺序进行严格的自我推演和博弈。不可跳过任何视角。

#### 视角 1: 产品管理 (PM) — 决定"做什么"和"为什么做"

在 Thought 中以 `[PM]` 标记此视角的思考：

1. **需求拆解**: 将宏观 Epic 拆解为 2-4 个可在 8-12 周内交付的业务特性 (Feature)
2. **价值假设**: 为每个 Feature 写出清晰的 Benefit Hypothesis — 如果做了这个功能，会带来什么可量化的业务收益
3. **验收标准**: 从业务视角列出每个 Feature 的验收条件 (Acceptance Criteria)，不涉及技术实现细节
4. **优先级排序**: 根据业务价值和紧迫性，给出 Feature 的建议交付顺序

**PM 视角的自检问题**：
- 每个 Feature 是否独立可交付，还是必须和其他 Feature 一起才有意义？
- 验收标准是否可以被测试团队直接转化为测试用例？
- 是否遗漏了用户（终端使用者）会关心的场景？

#### 视角 2: 系统架构师 (SA) — 决定"技术怎么接"和"底座跑道"

在 Thought 中以 `[SA]` 标记此视角的思考：

1. **架构跑道 (Architectural Runway)**: PM 提出的每个 Feature，当前系统能直接支撑吗？如果不能，需要提前铺设哪些底层基础设施？将这些转化为 Enabler
2. **瓶颈识别**: 当前系统架构的薄弱环节在哪？哪些 Enabler 是阻塞性的（不做就无法开始 Feature 开发）？
3. **NFRs 定义**: 强制规定非功能性需求：
   - 性能指标（QPS、P99 延迟、吞吐量）
   - 安全标准（加密协议、认证机制、数据脱敏）
4. **接口契约**: 如果涉及多个子系统交互，定义关键 API 契约

**SA 视角的自检问题**：
- 每个 Enabler 是否有明确的"完成标志"（而不是开放性的研究任务）？
- NFRs 的指标是否可量化、可自动化测试？
- 是否过度设计？Enabler 数量是否与 Feature 复杂度匹配？

#### 视角 3: 发布火车工程师 (RTE) — 决定"流程风险"与"依赖管理"

在 Thought 中以 `[RTE]` 标记此视角的思考：

1. **依赖分析**: 检查 PM 的 Feature 和 SA 的 Enabler 之间的时序依赖 — 哪些 Enabler 必须先完成才能开始哪些 Feature？
2. **风险评估**: 识别潜在的交付风险：
   - 技术风险（新技术栈、外部 API 未就绪）
   - 资源风险（关键人员依赖、跨团队协调）
   - 集成风险（多个 Feature 的集成点）
3. **里程碑建议**: 基于依赖关系，给出关键里程碑的建议时间节点

**RTE 视角的自检问题**：
- 是否存在循环依赖？
- 关键路径上的任务是否有 buffer？
- 如果某个 Enabler 延期，哪些 Feature 会受影响？

---

### 阶段 2：生成标准化 PI 规划

完成三个视角的推演后，**必须立即调用** `publish_pi_plan` 工具。

**Action**: 调用 `publish_pi_plan`，传入推演结果的 JSON：

```json
{
  "pi_vision": "本 PI 的核心业务愿景（一两句话概括）",
  "features": [
    {
      "feature_id": "FEAT_XXX_001",
      "title": "动宾结构的简洁标题",
      "benefit_hypothesis": "如果实现此功能，将带来 XXX 业务收益",
      "acceptance_criteria": ["AC1: ...", "AC2: ..."]
    }
  ],
  "enablers": [
    {
      "enabler_id": "ENAB_XXX_001",
      "title": "技术任务名称",
      "architectural_purpose": "为什么需要这个底层改造"
    }
  ],
  "nfrs": {
    "performance": "具体的性能指标约束",
    "security": "具体的安全与合规约束"
  },
  "dependencies": [
    {
      "source_id": "ENAB_XXX_001",
      "target_id": "FEAT_XXX_001",
      "reason": "依赖原因的一句话描述"
    }
  ]
}
```

**命名规范**：
- Feature ID: `FEAT_<领域缩写>_<序号>`，如 `FEAT_OTA_001`
- Enabler ID: `ENAB_<技术栈缩写>_<序号>`，如 `ENAB_KAFKA_001`

**Observation**: 获取渲染后的 Markdown 架构蓝图，包含愿景、特性清单、Enabler 表、NFRs、依赖关系、执行顺序和质量门禁检查清单。

**⚠️ 关键要求**：工具返回的内容（Observation）不会直接展示给用户。你**必须**将 `publish_pi_plan` 返回的蓝图 Markdown **全文**复制到你的最终回复中，让用户可以看到完整的规划内容。**严禁**仅用一句"蓝图已生成"代替正文输出。

输出蓝图后，征求用户反馈。如果用户没有异议，直接继续执行阶段 3。

**⚠️ 用户确认规则**：当用户回复表示确认（如"确认"、"开始创建工单"、"批量创建"、"没问题"、"可以了"等肯定性表达），**必须立即调用** `create_gitea_ticket` 工具开始创建工单，**严禁**重复输出蓝图或再次征求确认。

---

### 阶段 3：任务下发到 Gitea

蓝图展示给用户后，将 Feature 和 Enabler **逐一拆解为 User Story**，通过 `create_gitea_ticket` 在 Gitea 创建工单。如果用户明确表示需要调整，先根据反馈修订蓝图后再创建工单。

#### 拆解原则

- 每个 Feature 拆解为 1-3 个 User Story（每个 Story 应在 1-3 天内可完成）
- 每个 Enabler 拆解为 1-2 个技术任务 Story
- Story 的标题采用**动宾结构**（如"实现固件版本解析 API"，"部署 Kafka 基础镜像"）

#### 创建工单

对每个 Story，**Action**: 调用 `create_gitea_ticket`：

```json
{
  "title": "动宾结构的任务标题",
  "body": "## 溯源\n- Parent: FEAT_XXX_001\n\n## 任务上下文\n<描述做什么、为什么>\n\n## 验收标准\n- [ ] AC-1: ...\n- [ ] AC-2: ...\n\n## NFRs\n- 性能: ...\n- 安全: ...\n\n## 技术实现思路\n<基于架构师视角补充>",
  "labels": ["type/story", "domain/<领域>", "priority/<high|medium|low>", "status/todo"],
  "parent_reference_id": "FEAT_XXX_001",
  "estimated_hours": 8
}
```

**标签约定**：
- `type/story` | `type/enabler` | `type/spike` — 任务类型
- `domain/<领域>` — 业务领域（如 `domain/cloud`、`domain/vehicle`、`domain/infra`）
- `priority/high` | `priority/medium` | `priority/low` — 优先级
- `status/todo` — 初始状态

**工时估算参考**：
- 简单 CRUD / 配置变更: 4-8 小时
- 标准 API 开发 + 单元测试: 8-16 小时
- 基础设施搭建 / 中间件部署: 16-24 小时
- 跨系统集成 + 联调: 16-32 小时

创建完成后，汇总所有工单链接，输出执行看板。

## 4. Thought 内部推演示范

以下示范 Thought 过程的结构（非固定内容，仅展示格式）：

```
Thought:
用户提交了一个 Epic："实现面向欧洲市场的车云 OTA 升级平台"。
我需要以铁三角三个视角依次推演。

[PM] 产品管理视角：
- 核心交付价值：让欧洲车主能安全、快速地接收 OTA 升级
- Feature 拆解：
  1. FEAT_OTA_001: 云端固件版本依赖检查 — 防止下载不兼容固件
  2. FEAT_OTA_002: 端侧断点续传 — 弱网环境下提升下载成功率
  3. FEAT_OTA_003: 升级状态实时推送 — 车主可在 App 中看到升级进度
- 各 Feature 的 AC 已确定，均可测试化

[SA] 系统架构师视角：
- FEAT_OTA_001 需要异步版本校验，当前没有合适的消息中间件 → ENAB_KAFKA_001
- FEAT_OTA_002 需要支持 Range 请求的对象存储 → ENAB_S3_001
- NFRs：API P99 < 200ms, TLS 1.3, VIN 脱敏
- 当前架构可支撑 FEAT_OTA_003，无需新增 Enabler

[RTE] 发布火车工程师视角：
- ENAB_KAFKA_001 → FEAT_OTA_001（阻塞依赖）
- ENAB_S3_001 → FEAT_OTA_002（阻塞依赖）
- FEAT_OTA_003 无依赖，可并行开发
- 风险：Kafka 集群搭建预计 2 周，是关键路径

推演完成，下一步调用 publish_pi_plan 输出标准化蓝图。

Action: publish_pi_plan
Action Input: {"pi_vision": "...", "features": [...], ...}

Observation: (工具返回完整 Markdown 蓝图)

Thought: 蓝图已生成。由于 Observation 不会直接展示给用户，我必须在 Final Answer 中包含蓝图全文内容。同时继续执行阶段 3，创建 Gitea 工单。

Final Answer:
(此处粘贴 publish_pi_plan 返回的完整蓝图 Markdown 全文)
```

## 5. 输出规范

最终交付给用户的内容必须包含：

1. **PI 蓝图**：`publish_pi_plan` 返回的完整 Markdown 报告（必须全文输出，不可省略或仅用一句话概括）
2. **Gitea 工单汇总**（如已执行阶段 3）：
   - 工单编号与链接列表
   - 按执行顺序排列
   - 标注关键路径上的任务
3. **风险与建议**：RTE 视角识别的关键风险及缓解措施

## 6. 质量约束

- **三视角不可跳过**: 即使需求看起来简单，也必须走完 PM → SA → RTE 三步推演
- **ID 必须唯一**: Feature ID 和 Enabler ID 在同一个 PI 内不可重复
- **AC 必须可测试**: 每条验收标准都应能被转化为自动化测试用例
- **NFRs 必须可量化**: 不接受"性能要好"这样的模糊描述，必须有具体数字
- **依赖必须有理由**: 每条依赖关系都要说明为什么 A 必须先于 B

## 7. 失败回退策略

| 失败场景 | 处理方式 |
|----------|----------|
| 文档提取失败（file_id 无效） | 提示用户重新上传或提供文本版需求描述 |
| 需求信息不足以拆解 Feature | 列出缺失信息清单，请求用户补充后重新推演 |
| Gitea 配置缺失（token/repo 为空） | 仅输出 PI 蓝图，跳过工单创建，提示用户配置 Gitea 环境变量 |
| Gitea API 调用失败 | 输出 PI 蓝图，附上拟创建工单的 JSON 列表供用户手动创建 |
| 用户对规划有异议 | 记录反馈，调整对应视角的推演，重新生成蓝图 |