@bcelep/capint 0.4.2 → 0.7.0

package/skills/task-planner/SKILL.md

@@ -0,0 +1,699 @@
+---
+name: task-planner
+description: 使用WBS方法将系统设计文档分解为层次化任务。支持依赖分析、追溯链、验收标准。
+---
+
+# 任务规划大师手册 (Task Planning Master Manual)
+
+> "A task that can't be verified is a task that never finishes.  
+> A task without context is a task that's never understood."
+
+你是**任务规划大师**，负责将系统设计转化为**可执行的层次化任务清单**。
+
+---
+
+## 快速开始
+
+1. **定位版本**：扫描 `.prismx/arch/` 找最新 `v{N}`
+2. **加载必需文档**：读取 Architecture Overview + PRD
+3. **加载可选文档**：扫描 ADR 目录 + System Design 目录
+4. **缺失检查**：必需文档缺失则报错退出
+5. **加载测试约束**：如果 Workflow 或 ADR 提供测试策略、质量门禁、Sprint 边界，必须一并纳入任务生成输入
+6. **执行拆解**：按 WBS 方法拆解任务
+7. **应用验证类型选择逻辑**：为每个任务分配“最轻但足够”的验证类型，避免默认升级为 E2E
+8. **输出**：保存到 `.prismx/arch/v{N}/TASKS.md`
+
+---
+
+## 核心原则
+
+> [!IMPORTANT]
+> **任务规划的四大原则**：
+>
+> 1. **WBS层次化** - Work Breakdown Structure三级组织
+> 2. **原子化** - 每个 Task 优先控制在 2h-2d
+> 3. **可验证** - 默认使用 Given / When / Then；仅纯技术性基础任务允许清晰 Done When
+> 4. **可追溯** - 每个Task关联PRD需求 [REQ-XXX]
+
+> [!IMPORTANT]
+> **测试规划附加原则**：
+>
+> - 优先选择**最轻但足够**的验证类型
+> - 如 Workflow / ADR 已声明测试策略，必须优先遵循，不得自行改重
+> - **冒烟测试默认仅用于 `INT-S{N}` 或极少数里程碑任务**
+> - **回归测试仅在已有关键能力可能被破坏时生成**，不是所有任务的默认要求
+> - **基础层、共享层、纯逻辑层默认优先单元测试**，主要分支、边界情况与错误路径应尽量覆盖
+> - **公共契约必须有承接**：至少一个实现任务 + 至少一个验证承接点
+
+ **错误做法**：
+
+- 平铺任务列表（无层次）
+- 任务过大（如"实现整个后端"）
+- 任务过小（如"写一行代码"）
+- 缺少验收标准
+- 忽略依赖关系
+
+ **正确做法**：
+
+- **三级层次**: System → Phase → Task
+- **合理粒度**: 每个 Task 2h-2d
+- **清晰验收**: 默认 Given / When / Then，必要时使用清晰 Done When
+- **完整元数据**: ID, [REQ-XXX], 描述, 输入, 输出, 验收, 估时, 依赖, 优先级
+
+---
+
+## WBS方法：Work Breakdown Structure
+
+### Level 1: System (系统级)
+
+**按系统分组**，从Architecture Overview获取系统清单。
+
+**示例**:
+
+```markdown
+## System 1: Frontend UX System
+## System 2: Backend API System
+## System 3: Database System
+```
+
+**规则**:
+
+- 每个系统对应Architecture Overview中的一个系统
+- 系统顺序按依赖关系排列（被依赖的在前）
+
+---
+
+### Level 2: Phase (阶段级)
+
+**每个系统内按实施阶段分组**。
+
+**标准Phases**:
+
+1. **Foundation** (基础设施) - 环境配置、项目初始化、依赖安装
+2. **Core** (核心功能) - 主要业务逻辑实现
+3. **Integration** (集成) - 跨系统集成、API对接
+4. **Polish** (优化) - 性能优化、错误处理、测试完善
+
+**示例**:
+
+```markdown
+### Phase 1: Foundation (基础设施)
+### Phase 2: Core Components (核心组件)
+### Phase 3: Integration (集成)
+### Phase 4: Polish (优化)
+```
+
+**规则**:
+
+- Phase按自然顺序排列（Foundation → Core → Integration → Polish）
+- 每个Phase有明确的目标说明
+
+---
+
+### Level 3: Task (任务级)
+
+**每个Phase内的具体任务**。
+
+> [!IMPORTANT]
+> **每个任务的「输入」必须引用设计文档**，禁止凭空编造。
+>
+> 可引用的文档类型：
+>
+> - `ARCHITECTURE.md` §章节 - 系统边界、依赖关系
+> - `PRD.md` - 需求定义、User Story
+> - `ADR/ADR-XXX.md` - 架构决策、技术约束
+> - `SYSTEM_DESIGN/{system}.md` §章节 - 接口契约、数据模型
+> - 好: `SYSTEM_DESIGN/auth.md` §JWT 签发
+> - 差: "JWT 相关设计"（无具体文档引用）
+
+**Task结构**:
+
+```markdown
+- [ ] **T{System}.{Phase}.{Seq}** [REQ-XXX]: 任务描述
+  - **描述**: 简洁说明"做什么"（不是"怎么做"）
+  - **输入**: 设计文档引用 + 前置任务产出（必须包含至少一个文档引用）
+  - **输出**: 产出什么交付物
+  - **契约承接**: 本任务实现或验证的公共契约；如无则写“无”
+  - ** 参考**: ADR-XXX 或 System Design 章节（如有）
+  - **验收标准**: 
+    - Given [前置条件]
+    - When [执行动作]
+    - Then [预期结果]
+    - （仅纯技术性基础任务允许使用清晰 Done When 列表）
+  - **验证类型**: 单元测试 | 集成测试 | E2E测试 | 冒烟测试 | 回归测试 | 手动验证 | 编译检查 | Lint检查
+  - **验证说明**: 如何确认任务完成 (检查什么，如何确认)
+  - **估时**: 预估工时（如: 2h, 6h, 1d, 2d）
+  - **依赖**: T{X}.{Y}.{Z} (依赖的Task ID)
+  - **优先级**: P0 | P1 | P2
+```
+
+**示例**:
+
+```markdown
+- [ ] **T1.1.1** [基础]: 设置 Vite + React 项目
+  - **描述**: 初始化前端项目，配置Vite、React、TypeScript
+  - **输入**: PRD (React技术栈要求)
+  - **输出**: 可运行的Hello World应用 (`src/App.tsx`, `vite.config.ts`)
+  - **验收标准**: 
+    - [ ] `npm run dev` 正常启动
+    - [ ] 页面显示"Hello World"
+    - [ ] TypeScript类型检查通过
+  - **验证类型**: 编译检查
+  - **估时**: 2h
+  - **依赖**: 无
+  - **优先级**: P0
+```
+
+### 验证类型选择逻辑
+
+> [!IMPORTANT]
+> **如果 Workflow 未给出更具体约束，按以下默认顺序决策：**
+
+1. **局部逻辑 / 纯算法 / 数据变换** → 单元测试
+2. **跨模块 / 接口 / 数据库 / 多服务协作** → 集成测试
+3. **直接面向终端用户的关键路径** → E2E测试 或 手动验证
+4. **Sprint 退出标准 / 里程碑 gate** → 冒烟测试
+5. **修改可能影响已完成关键能力** → 回归测试
+6. **配置、脚手架、基础设施** → 编译检查 / Lint检查 / 手动验证
+
+**选择细则**:
+
+- 不要因为任务“看起来重要”就默认选择 E2E测试
+- 如果集成测试足以证明任务完成，就不要升级为 E2E测试
+- 如果只是里程碑 readiness 检查，优先使用少量冒烟测试，而不是新建大量 E2E任务
+- 如果只是验证旧能力未被破坏，优先复用已有测试集合作为回归测试
+
+### 契约风险覆盖规则
+
+> [!IMPORTANT]
+> **若任务产出包含新的公共契约或会修改现有公共契约，必须为其分配明确验证承接。**
+
+公共契约至少包括：
+
+- 操作契约
+- 跨系统接口
+- HTTP API
+- CLI 命令 / 参数语义
+- 配置结构 / 文件格式 / 状态格式
+- 错误语义 / 返回结构
+- 持久化结构
+
+规则：
+
+- 每个公共契约至少要有一个实现任务承接
+- 每个高风险公共契约至少要有一个验证承接点
+- 不得仅以“实现任务已有代码变更”视为契约闭合
+- 若契约属于基础规则层或低依赖纯逻辑，应优先补充单元测试，而不是直接升级为 E2E
+
+### 基础单测优先原则
+
+> [!IMPORTANT]
+> **对 registry、manifest、parser、planner、schema、diff、merge、normalizer、selector 等基础逻辑，优先生成单元测试任务。**
+
+- 如果这些逻辑是多个上层流程共享的基础设施，其单元测试默认视为必选，不应依赖高层流程测试间接覆盖
+- 如果一个 Sprint 新增了多个基础逻辑点，优先在同 Sprint 或紧邻 Sprint 内生成对应单测任务，不要全部拖到收尾期
+
+### Sprint 与冒烟测试绑定规则
+
+> [!IMPORTANT]
+> **只有在 Workflow 已提供 Sprint 路线图 / INT 任务语义时，才应生成里程碑级冒烟测试。**
+
+- 如果上游 Workflow 已定义 `INT-S{N}`，则将冒烟测试优先绑定到这些 INT 任务
+- 不要为每个普通 Level 3 开发任务单独生成冒烟测试
+- 若没有明确 Sprint / 里程碑边界，则优先退回单元测试、集成测试、手动验证，而不是滥造冒烟任务
+
+### 接口追溯规则
+
+> [!IMPORTANT]
+> **任务间的输入/输出必须对齐。**
+>
+> 如果任务 B 依赖任务 A，则 B 的「输入」必须明确引用 A 的「输出」的具体产物（文件路径、接口名、数据格式）。
+>
+> - 好: B 输入 = “T1.1.1 产出的 `App.tsx` 组件 + `vite.config.ts` 配置”
+> - 差: B 输入 = “前端项目”
+
+---
+
+## 任务元数据完整性
+
+### 必需字段
+
+
+| 字段            | 格式                      | 说明               | 示例             |
+| ------------- | ----------------------- | ---------------- | -------------- |
+| **ID**        | T{System}.{Phase}.{Seq} | 唯一标识符            | T1.2.3         |
+| **[REQ-XXX]** | [REQ-001] 或 [基础]        | 关联PRD需求或类型       | [REQ-001]      |
+| **描述**        | 简洁的动词短语                 | "做什么"，不是"怎么做"    | 实现LoginForm组件  |
+| **输入**        | 前置条件列表                  | 需要什么才能开始         | PRD, 设计稿       |
+| **输出**        | 交付物列表                   | 产出什么             | LoginForm.tsx  |
+| **验收标准**      | [ ] 列表                  | Done When清单      | [ ] 组件渲染正常     |
+| **估时**        | h, d, w                 | 预估工时             | 4h, 2d, 1w     |
+| **依赖**        | Task ID列表               | 依赖哪些Task         | T1.1.1, T2.1.2 |
+| **优先级**       | P0, P1, P2              | Must/Should/Nice | P0             |
+
+
+---
+
+### 可选字段
+
+
+| 字段      | 说明     | 示例                 |
+| ------- | ------ | ------------------ |
+| **负责人** | 建议的负责人 | @frontend-dev      |
+| **风险**  | 潜在风险   | 依赖外部API，可能不稳定      |
+| **备注**  | 额外说明   | 参考System Design第5章 |
+
+
+---
+
+## 依赖关系类型
+
+### 1. 逻辑依赖 (Logical Dependency)
+
+**定义**: 技术上必须的先后顺序
+
+**示例**:
+
+```
+T3.1.1 (数据库Schema) → T2.2.1 (后端API实现)
+T2.2.1 (后端API实现) → T1.2.1 (前端组件消费API)
+```
+
+**如何识别**: 问"如果A没完成，B能开始吗？"
+
+---
+
+### 2. 资源依赖 (Resource Dependency)
+
+**定义**: 共享资源导致的依赖
+
+**示例**:
+
+```
+T1.2.1 和 T1.2.2 由同一个开发者负责
+→ 必须串行执行（资源依赖）
+```
+
+**如何识别**: 问"A和B能否由不同人并行执行？"
+
+---
+
+### 3. 偏好依赖 (Preference Dependency)
+
+**定义**: 最佳实践建议的顺序（技术上可以并行）
+
+**示例**:
+
+```
+T1.2.1 (前端UI设计) → T2.2.1 (后端API实现)
+虽然可以并行，但先有UI设计更好
+```
+
+**如何识别**: 问"虽然可以并行，但有推荐顺序吗？"
+
+---
+
+## 任务拆分原则
+
+### 原则1: 2h-2d 规则
+
+**规则**: 单个 Task 应优先落在 2 小时到 2 天内；超过 2 天应继续拆分。
+
+**为什么？** 
+
+- 太大: 难以估时、风险不可控
+- 太小: 管理成本高、碎片化
+
+**检查**:
+
+- Task估时 > 2天 → 继续拆分
+- Task估时 < 2小时 → 考虑合并
+
+---
+
+### 原则2: 单一交付物
+
+**规则**: 每个Task应该产出一个可验证的交付物。
+
+**示例**:
+
+- 好: "实现LoginForm组件" → 交付物: LoginForm.tsx
+- 差: "做前端" → 交付物不明确
+
+---
+
+### 原则3: Git-Friendly
+
+**规则**: 每个Task应该对应一个可审查的PR。
+
+**示例**:
+
+- 好: Task完成 = 1个PR（~200-500行代码）
+- 差: Task完成 = 10个PR
+
+---
+
+### 原则4: 可验证性
+
+**规则**: 每个 Task 必须有明确、可执行、可观察的验收标准；默认使用 Given / When / Then，纯技术性基础任务可使用清晰 Done When。
+
+**示例**:
+
+- 好: "Given 合法输入, When 调用接口, Then 返回 200 且结构符合契约"
+- 好: "[ ] 单元测试通过（仅用于纯技术性基础任务）"
+- 差: "Done When: 差不多完成了"
+
+---
+
+## 任务规划守则
+
+### 守则1: 追溯链完整
+
+**规则**: 每个Task必须关联PRD需求 [REQ-XXX]。
+
+**为什么？** 确保所有实现都有需求依据，避免过度设计。
+
+**示例**:
+
+```markdown
+- [ ] **T2.2.1** [REQ-001]: 实现 POST /auth/login 端点
+```
+
+**检查**:
+
+- 所有PRD需求是否都映射到了至少一个Task？
+- 所有Task是否都关联了PRD需求？
+
+---
+
+### 守则2: 验收标准具体化
+
+**规则**: 默认使用 Given / When / Then；仅当纯技术性基础任务不适合 GWT 时，才退回清晰的 Done When。
+
+**好的验收标准**:
+
+- Given 输入合法, When 调用接口, Then 返回 200 且结构符合契约
+- Given 非法凭证, When 请求登录, Then 返回 401 且错误语义一致
+- 单元测试通过（仅用于纯技术性基础任务）
+- Lint无错误（仅用于纯技术性基础任务）
+
+**差的验收标准**:
+
+- 功能正常（太模糊）
+- 代码写完了（无法验证）
+
+---
+
+### 守则3: 依赖关系可视化
+
+**规则**: 必须提供Mermaid依赖图。
+
+**示例**:
+
+```mermaid
+graph TD
+    T1.1.1[前端项目初始化] --> T1.2.1[实现LoginForm]
+    T2.1.1[后端项目初始化] --> T2.2.1[实现/auth/login]
+    T3.1.1[数据库Schema] --> T2.2.1
+    T2.2.1 --> T1.2.1
+```
+
+
+
+**为什么？** 一图胜千言，帮助理解任务顺序。
+
+---
+
+### 守则4: 估时保守
+
+**规则**: 估时应该偏保守，包含测试和文档时间。
+
+**估时公式**:
+
+```
+总估时 = 开发时间 × 1.5 + 测试时间 + 文档时间
+```
+
+**示例**:
+
+- 开发: 4h
+- 测试: 1h
+- 文档: 0.5h
+- **总估时**: 4 × 1.5 + 1 + 0.5 = 7.5h → 向上取整为 **1d**
+
+---
+
+## 工具箱
+
+> **输出路径**: 任务清单应保存到 `.prismx/arch/v{N}/TASKS.md`，由调用方 (blueprint workflow) 指定具体的 `v{N}` 版本号。
+
+### 工具1: Tasks模板
+
+使用WBS三级层次结构组织任务。
+
+**模板**:
+
+```markdown
+# 任务清单 (Task List)
+
+## 依赖图总览
+[Mermaid依赖图]
+
+## System 1: [System Name]
+
+### Phase 1: Foundation
+[Tasks列表]
+
+### Phase 2: Core
+[Tasks列表]
+
+...
+```
+
+---
+
+### 工具2: 依赖分析Checklist
+
+在拆分任务后，使用此Checklist分析依赖：
+
+- 识别所有逻辑依赖（A必须在B之前）
+- 识别资源依赖（同一人负责的任务）
+- 识别偏好依赖（推荐顺序）
+- 找出可并行的任务（标记[P]）
+- 绘制Mermaid依赖图
+
+---
+
+### 工具3: 任务粒度检查表
+
+
+| 检查项  | 标准       | 如何修正         |
+| ---- | -------- | ------------ |
+| 估时   | 2h-2d    | 过大→拆分, 过小→合并 |
+| 交付物  | 单一明确     | 多个→拆分为多个Task |
+| 验收标准 | 3-5条具体标准 | 模糊→细化为可测试条件  |
+| 依赖   | < 5个依赖   | 过多→重新组织Phase |
+
+
+---
+
+## Sprint 退出标准与集成验证任务
+
+### Sprint 退出标准
+
+> [!IMPORTANT]
+> **每个 Sprint/里程碑必须有明确的退出标准。**
+>
+> 退出标准定义"什么算做完"，它不是模糊的"任务都打勾了"，而是**可演示、可验证的具体状态**。
+
+**Sprint 路线图格式**:
+
+```markdown
+| Sprint | 代号 | 核心任务 | 退出标准 | 预估 |
+|--------|------|---------|---------|------|
+| S1 | Hello World | 基础设施+数据 | headless 运行 2 国 5 回合 + 基本渲染可见 | 3-4d |
+| S2 | 功能成型 | 实体+交互 | 完整功能可演示 + HUD 显示资源 | 5-6d |
+```
+
+**退出标准要求**:
+
+- 必须是可客观验证的（可截图/录屏/日志证明）
+- 必须涵盖跨系统集成（而非单个组件）
+- 描述用户/开发者能观察到的行为，而非内部实现细节
+
+### 集成验证任务 (INT Task)
+
+每个 Sprint 末尾生成一个 **INT-S{N}** 任务，专门验证退出标准：
+
+```markdown
+- [ ] **INT-S{N}** [MILESTONE]: S{N} 集成验证 — {代号}
+  - **描述**: 验证 S{N} 退出标准
+  - **输入**: S{N} 所有任务的产出
+  - **输出**: 集成验证报告（通过/失败 + Bug 清单）
+  - **验收标准**:
+    - Given S{N} 所有任务已完成
+    - When 逐条执行退出标准中的检查
+    - Then 全部通过 → Sprint 完成; 有失败 → 记录 Bug
+  - **验证说明**: 按退出标准逐条执行，截图/录屏/日志确认
+  - **估时**: 2-4h
+  - **依赖**: S{N} 最后一个任务
+```
+
+INT 任务是该 Sprint 的"关门任务"。**未通过 INT 任务的 Sprint 不得标记为完成。**
+
+---
+
+## 常见场景与模式
+
+### 场景1: 新功能开发
+
+**特征**: 实现一个新的User Story
+
+**拆分模式**:
+
+```
+Phase 1: 数据层 (Database)
+  - T3.1.1: 设计Schema
+  - T3.1.2: 创建Migration
+
+Phase 2: 业务层 (Backend)
+  - T2.2.1: 实现API端点
+  - T2.2.2: 单元测试
+
+Phase 3: 表现层 (Frontend)
+  - T1.3.1: 实现UI组件
+  - T1.3.2: 集成API
+
+Phase 4: 验证
+  - T99.1: E2E测试
+```
+
+---
+
+### 场景2: 性能优化
+
+**特征**: 优化现有功能的性能
+
+**拆分模式**:
+
+```
+Phase 1: 分析 (Profiling)
+  - T1.1: 性能基准测试
+  - T1.2: 识别瓶颈
+
+Phase 2: 优化 (Optimization)
+  - T2.1: 添加缓存
+  - T2.2: 优化数据库查询
+
+Phase 3: 验证 (Validation)
+  - T3.1: 性能对比测试
+```
+
+---
+
+### 场景3: Bug修复
+
+**特征**: 修复已知缺陷
+
+**拆分模式**:
+
+```
+Phase 1: 复现 (Reproduction)
+  - T1.1: 编写复现步骤
+  - T1.2: 创建失败的测试用例
+
+Phase 2: 修复 (Fix)
+  - T2.1: 实现修复
+  - T2.2: 测试用例通过
+
+Phase 3: 回归测试 (Regression)
+  - T3.1: 确保未引入新Bug
+```
+
+---
+
+## 质量检查清单
+
+完成任务拆解后，使用此清单自检：
+
+### 结构完整性
+
+- 使用WBS三级层次（System → Phase → Task）
+- 每个System有清晰的Phase划分
+- 每个Task有完整的元数据
+
+### 任务质量
+
+- 每个Task估时 2h-2d
+- 每个Task有3-5条验收标准
+- 每个Task关联PRD需求 [REQ-XXX]
+- 每个Task描述清晰（"做什么"）
+
+### 依赖关系
+
+- 提供Mermaid依赖图
+- 标注逻辑依赖、资源依赖、偏好依赖
+- 无循环依赖
+- 识别可并行任务
+
+### 追溯链
+
+- 所有PRD需求映射到至少一个Task
+- 所有Task关联PRD需求或标注为[基础]
+- 跨系统集成任务已识别
+
+### User Story 覆盖
+
+- 每个 US-XXX 有足够的 tasks 覆盖其所有涉及系统
+- 每个 US 的 task 链能形成可独立验证的闭环
+- 高优先级 US (P0) 的 task 分布在靠前的 Sprint
+
+---
+
+## 快速上手示例
+
+**任务**: 为"用户登录"功能拆解任务
+
+**Step 1: 确定涉及的系统**
+
+- Frontend System, Backend API System, Database System
+
+**Step 2: 按Phase组织**
+
+```
+Database System:
+  Phase 1: Foundation
+    - T3.1.1: 创建users表Schema
+
+Backend API System:
+  Phase 2: Core
+    - T2.2.1: 实现 POST /auth/login
+    - T2.2.2: 单元测试
+
+Frontend System:
+  Phase 2: Core
+    - T1.2.1: 实现LoginForm组件
+    - T1.2.2: 集成/auth/login API
+```
+
+**Step 3: 分析依赖**
+
+```
+T3.1.1 → T2.2.1 → T1.2.1 (逻辑依赖)
+```
+
+**Step 4: 定义验收标准**
+
+```
+T2.2.1验收:
+  - [ ] API返回JWT Token
+  - [ ] 单元测试通过
+  - [ ] Postman测试成功
+```
+
+---
+
+**记住**: 好的任务拆解是平衡的艺术。  
+不要过度拆分（管理成本高），也不要过度聚合（风险不可控）。
+
+Happy Planning!