flower-trellis 0.1.0

package/enhancements/0.6/.agents/skills/trellis-verify-task/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: trellis-verify-task
+description: "Audit task planning artifacts (prd.md, plus design.md and implement.md when present) against the original requirements doc AND across layers via forward checks + reverse coverage scans + cross-layer consistency; flag missing/misinterpreted/embellished/UI-copy-mismatch/cross-layer-drift items and propose ONE consolidated edit list. Triggers: 「校验任务」「校验三件套」「对照原始需求」「verify task spec」「verify task」. Not for PRD generation (trellis-brainstorm/trellis-extract-prd) or implementation-vs-spec check (trellis-check-all)."
+---
+# 校验任务 — 三件套统一校验
+
+对照用户提供的原始需求文档（需求规格说明、PRD 截图、文字描述等），逐条校验任务规划三件套（`prd.md` / `design.md` / `implement.md`）是否准确、一致、完整。校验范围按任务层级动态扩展：
+
+- **Lightweight 任务**（只有 `prd.md`）：仅做 PRD 准确性 + 覆盖度校验
+- **Complex 任务**（含 `design.md` 和/或 `implement.md`）：在上述基础上追加 PRD↔Design / Design↔Implement / 跨层一致性三道校验
+
+发现的所有偏差**一次性汇总**为一份完整修正清单，获得用户**单次确认**后批量更新，不分层逐次确认。
+
+---
+
+## 核心原则（不可违反）
+
+1. **原始需求文档是唯一权威** — PRD 必须忠实反映原始需求；Design / Implement 必须忠实反映 PRD，不得自行"理解"、"推演"或"发挥"
+2. **逐条对照，不跳不漏** — 每一层都做正反双向校验（正向看上层有的下层是否覆盖；反向看下层有的能否回溯到上层）
+3. **标记偏差类型** — 区分"缺失 / 曲解 / 发挥过度 / 措辞不准 / 越界 / 跨层漂移"
+4. **文案必须逐字一致** — 原始需求中出现的用户可见文案（按钮文字、提示语、Toast、弹窗内容、表头、placeholder 等）必须在 PRD、Design、Implement 三个文档中**逐字一致**；任何一处不一致直接标记为 ❌ 曲解（不是 ⚠️ 措辞偏差），因为前端会照搬最后看到的版本实现
+5. **只改偏差，不改结构** — 修正内容错误，不改变文档整体格式框架
+6. **版本变更全覆盖** — 原始需求中属于本次版本的所有变更内容都必须被某个任务/PRD 覆盖，不得遗漏
+7. **跨层不可发明** — 下层（Design / Implement）不得引入上层（PRD）未提及的需求或行为；只能引入"实现上必需的技术决策"，并标注"实现必需"原因
+8. **修正清单一次性给完整** — 不要边发现边改，也不要按层分次请用户确认。一次扫完，一次给清单，一次确认，一次落盘
+
+---
+
+## 适用场景
+
+- 任务三件套刚写完，尚未进入开发，需要对照原始需求文档做正反双向核对
+- 需求文档更新后，想确认 PRD / Design / Implement 是否仍完整反映了最新版本的所有变更
+- 多任务 / 多 PRD 并行时，怀疑某次版本变更被漏挂到任何任务下
+- 怀疑 Design 或 Implement 跟 PRD 漂移（命名、边界、UI 文案任一不一致）
+
+---
+
+## 执行步骤
+
+### Step 1: 定位文件与判定任务层级
+
+```bash
+python3 ./.trellis/scripts/task.py list
+```
+
+读取任务目录下的文件，按存在性判定：
+
+| 文件存在情况 | 任务层级 | 校验范围 |
+|------------|---------|---------|
+| 只有 `prd.md` | Lightweight | 只跑 Step 3 + Step 3.5 |
+| `prd.md` + `design.md`（无 `implement.md`） | 部分 Complex | Step 3 / 3.5 / 4 / 6（跨层只校验 PRD↔Design 命名一致性） |
+| `prd.md` + `design.md` + `implement.md` | Complex | 全跑 Step 3 / 3.5 / 4 / 5 / 6 |
+| 缺 `prd.md` | 异常 | 提示用户先用 `trellis-extract-prd` 或 `trellis-brainstorm` 生成 PRD |
+
+> **不要假设任务一定是 Complex**。Trellis 0.6 明确允许 lightweight 只有 prd.md。
+
+### Step 2: 获取原始需求文档
+
+**必须主动获取原始需求文档来源**。按以下优先级查找：
+
+1. **任务目录下的附件** — 检查任务目录下是否有 `requirements.md`、`spec.md`、`需求.md`、`*.xlsx`、`*.pdf` 等文件
+2. **PRD 中的引用链接 / Technical Notes** — 检查 PRD 头部 `> 来源:` 行或 Technical Notes 中是否引用了外部文档路径
+3. **用户提供** — 如果上述都没有，**明确询问用户**：
+
+```markdown
+当前任务目录下未找到原始需求文档。请提供需求来源：
+
+1. **粘贴需求文本** — 直接粘贴原始需求内容
+2. **指定文件路径** — 告诉我需求文档在哪里
+3. **口述要点** — 口头说明关键需求点
+```
+
+> **[!] 严禁在没有原始需求文档的情况下进行 Step 3 / 3.5 校验** — 没有参照物的校验没有意义。Step 4 / 5 / 6 是内部一致性校验，不强依赖原始文档，但仍推荐先有原始文档以便交叉印证。
+
+### Step 3: 原始需求 ↔ prd.md（正向准确性校验）
+
+将原始需求文档分解为独立条目（逐个需求点 / AC / 功能点），然后逐条在 `prd.md` 中查找对应描述。
+
+对每一条标记状态：
+
+| 状态 | 含义 | 示例 |
+|------|------|------|
+| ✅ 准确 | PRD 忠实还原了原始需求 | — |
+| ⚠️ 措辞偏差 | 意思基本对，但措辞可能引起歧义 | 原始："下一行" → PRD："下一条未完结任务" |
+| ❌ 曲解 | PRD 理解错了原始需求的意思 | 原始："按当前列表排序" → PRD："按 taskNo 正序" |
+| ❌ 文案不一致 | UI 可见文案与原始需求不逐字一致（按钮、提示语、Toast、弹窗、表头、placeholder 等） | 原始：提示"确认提交？" → PRD："确认保存？" |
+| 🔴 缺失 | 原始需求有，PRD 里完全没提 | — |
+| 🟡 自行发挥 | PRD 写了原始需求没有的内容 | — |
+
+### Step 3.5: 覆盖度扫描（反向，原始 → PRD）
+
+Step 3 是**正向检查**（PRD 里的内容 → 原始文档里是否有）。
+Step 3.5 是**反向检查**（原始文档里本次版本的变更 → PRD 里是否覆盖）。
+
+#### 3.5.1 识别本次版本的所有变更内容
+
+**不要假设需求文档有固定格式。** 根据文档的实际结构，使用以下策略组合来识别变更：
+
+| 策略 | 适用场景 | 方法 |
+|------|---------|------|
+| **标记扫描** | 文档用标记标注变更（如 `[v1.2.0变更]`、`[新增]`、`[变更]`） | grep 全文搜索所有标记，**包括段落中间嵌入的标记** |
+| **需求总表** | 文档有需求列表/变更日志表格 | 读取表格中「版本」「更新内容」列，提取本次版本的条目 |
+| **章节对比** | 文档无显式标记，但有版本说明章节 | 读取版本说明/变更日志章节，提取所有变更描述 |
+| **全文语义** | 文档无任何结构化标记 | 通读全文，识别「新增」「变更」「调整」「优化」等动作词所在段落 |
+
+> **[!] 关键：必须扫描全文，不能只看目录/总表/标题。**
+> 很多变更是**嵌入在大段描述中间的字段级变更**，只看结构性位置会遗漏。
+
+#### 3.5.2 定位每个变更所属的需求单元
+
+对每个识别到的变更内容，确定它属于哪个需求单元（REQ 编号、功能模块、页面等）。
+定位方式取决于文档结构：
+- 有编号体系的：向上查找最近的需求标题
+- 无编号体系的：按章节/功能模块归类
+
+#### 3.5.3 交叉比对
+
+将所有变更按需求单元归组后，与 PRD 中已覆盖的范围做差集：
+
+| 检查项 | 说明 |
+|--------|------|
+| **已覆盖** | 变更所属需求单元在 PRD 中有对应任务/测试项 |
+| **未覆盖** | 变更所属需求单元完全不在 PRD 范围内 |
+| **部分覆盖** | 需求单元在 PRD 中有对应，但该单元内的某些变更点未被提及 |
+
+> **特别注意散射型变更**：同一个功能点可能散布在多个需求单元中。
+> 即使主需求已覆盖，也要检查所有关联位置。
+
+### Step 4: prd.md ↔ design.md（仅 Complex 任务）
+
+#### 4.1 正向：Design 中每个设计点能否回溯到 PRD
+
+逐个识别 `design.md` 中的设计单元（接口契约、数据模型、状态机、组件边界、流程步骤等）。对每一个设计单元判断：
+
+| 状态 | 含义 |
+|------|------|
+| ✅ 有依据 | 该设计点对应到 PRD 中的某条 Requirement / AC / Out of Scope 排除项 |
+| 🟡 实现必需 | PRD 未明示但实现上必需的技术决策（如：选 Redis 而非 in-memory）— **必须在 design.md 中已经标注"实现必需"理由**；未标注则降级为 ❌ |
+| ❌ 越界 | 设计了 PRD 未提及、且非"实现必需"的需求或行为（典型："顺手加了一个未来可能要的开关"）|
+
+#### 4.2 反向：PRD 中每个需求 / AC 是否在 Design 中有对应设计
+
+逐条扫 `prd.md` 的 Requirements 索引与 Acceptance Criteria 索引。对每一条判断：
+
+| 状态 | 含义 |
+|------|------|
+| ✅ 已覆盖 | Design 中有对应的接口 / 数据 / 流程设计 |
+| ⚠️ 部分覆盖 | Design 提到了但未给出完整契约 / 数据 / 边界 |
+| 🔴 漏覆盖 | Design 完全没设计这条需求 |
+| N/A | 该需求纯文案/UI 类，无需技术设计（需明确说明） |
+
+### Step 5: design.md ↔ implement.md（仅 Complex 任务）
+
+#### 5.1 正向：Implement 步骤能否回溯到 Design 设计点
+
+逐个识别 `implement.md` 中的执行步骤（建表 / 写 API / 写组件 / 加路由 / 验证命令 / rollback point 等）。对每一个步骤判断：
+
+| 状态 | 含义 |
+|------|------|
+| ✅ 有依据 | 对应到 design.md 中的某个设计单元 |
+| 🟡 实现必需 | Design 未明示但实现上必需的脚手架/工具步骤（如：加日志埋点、写迁移脚本）— 必须标注理由 |
+| ❌ 越界 | 引入了 design.md 未规划、且非"实现必需"的步骤（典型："顺便重构了无关模块"）|
+
+#### 5.2 反向：Design 中每个设计点是否在 Implement 中有对应步骤
+
+逐条扫 `design.md`。对每一个设计单元判断：
+
+| 状态 | 含义 |
+|------|------|
+| ✅ 已落地 | Implement 中有对应的执行步骤 |
+| ⚠️ 部分落地 | Implement 提到了但缺少验证命令 / rollback point |
+| 🔴 漏落地 | Implement 完全没规划这条设计 |
+
+### Step 6: 跨层一致性扫描（仅 Complex 任务）
+
+扫描三个文档中**同一实体**的表述是否一致。
+
+#### 6.1 命名一致性
+
+收集以下关键名词在三个文档中的所有出现位置，对照是否完全一致：
+
+- 数据实体名（如 `User` vs `Account`）
+- 字段名（如 `userId` vs `user_id` vs `uid`）
+- API 路径与方法（如 `/api/users` vs `/users`，`POST` vs `PUT`）
+- 状态枚举值（如 `pending` vs `PENDING` vs `Pending`）
+- 组件 / 模块名
+
+任一不一致 → 标记 ❌ 命名漂移。
+
+#### 6.2 UI 文案一致性
+
+收集 PRD「来源需求原文」中的所有用户可见文案，在 design.md 和 implement.md 中 grep 检查是否被引用且**逐字一致**：
+
+- 按钮文字、链接文字
+- 提示语、Toast、弹窗内容
+- 表头、placeholder、空态提示
+- 错误信息
+
+任一不一致 → 标记 ❌ 文案漂移（**直接 ❌，不是 ⚠️**，因为前端会照搬最后看到的版本）。
+
+#### 6.3 边界一致性
+
+对照 PRD 的「本任务范围」（✅ 实现 / ❌ 不在范围 / Out of Scope），检查：
+
+- design.md 是否设计了被 PRD 标记为「❌ 不在范围」的内容？
+- implement.md 是否计划了被 PRD 标记为「❌ 不在范围」的步骤？
+- design.md / implement.md 是否漏了 PRD 标记为「✅ 实现」的某条？
+
+任一违反 → 标记 ❌ 边界漂移。
+
+### Step 7: 输出统一报告（一次性，全层级一次出完）
+
+```markdown
+## 任务规划校验报告
+
+### 任务: <任务名称> ｜ 层级: <Lightweight / 部分 Complex / Complex>
+
+---
+
+### 一、原始需求 ↔ prd.md（准确性）
+
+#### 总览
+- 原始需求条目数: N
+- ✅ 准确: X 条 ｜ ⚠️ 措辞偏差: X 条 ｜ ❌ 曲解: X 条
+- ❌ 文案不一致: X 条 ｜ 🔴 缺失: X 条 ｜ 🟡 自行发挥: X 条
+
+#### 逐条对照（仅列出非 ✅ 项）
+##### <需求点>
+- **原始需求**: <原文摘抄 + 位置>
+- **PRD 描述**: <PRD 中的对应内容 + 位置>
+- **状态**: ❌ / ⚠️ / 🔴 / 🟡
+- **问题**: <说明>
+
+---
+
+### 二、原始需求 → prd.md（覆盖度）
+
+#### 总览
+- 原始文档本次版本变更总数: N
+- ✅ 已覆盖: X ｜ 🔴 未覆盖: X ｜ ⚠️ 部分覆盖: X
+
+#### 未覆盖 / 部分覆盖
+| 需求单元 | 位置 | 变更内容摘要 | 影响范围 |
+
+---
+
+### 三、prd.md ↔ design.md（仅 Complex）
+
+#### 3.1 正向（Design → PRD）
+- ✅ 有依据: X ｜ 🟡 实现必需: X ｜ ❌ 越界: X
+
+#### 3.2 反向（PRD → Design）
+- ✅ 已覆盖: X ｜ ⚠️ 部分覆盖: X ｜ 🔴 漏覆盖: X ｜ N/A: X
+
+#### 偏差明细（仅列出非 ✅ 项）
+
+---
+
+### 四、design.md ↔ implement.md（仅 Complex）
+
+#### 4.1 正向（Implement → Design）
+- ✅ 有依据: X ｜ 🟡 实现必需: X ｜ ❌ 越界: X
+
+#### 4.2 反向（Design → Implement）
+- ✅ 已落地: X ｜ ⚠️ 部分落地: X ｜ 🔴 漏落地: X
+
+#### 偏差明细
+
+---
+
+### 五、跨层一致性（仅 Complex）
+
+#### 5.1 命名漂移
+| 实体 | PRD 用法 | Design 用法 | Implement 用法 | 状态 |
+
+#### 5.2 文案漂移
+| 文案位置 | 原始需求 | PRD | Design | Implement | 状态 |
+
+#### 5.3 边界漂移
+| 条目 | PRD 范围标注 | Design / Implement 实际处理 | 状态 |
+
+---
+
+### 六、结论
+
+- **可发布**：✅ 全绿 / ⚠️ 仅有措辞偏差，可进入 Phase 2
+- **需修正**：存在 ❌ / 🔴 / 🟡 偏差，转 Step 8 修正清单
+- **覆盖缺口**：未覆盖的变更需要补任务还是补 PRD，等用户决策
+```
+
+> **关键**：一次性把六个 section 全部输出，**不要边写边问**、**不要按层分次确认**。
+
+### Step 8: 一次性完整修正清单（一次确认 → 批量落盘）
+
+把所有 ❌ / 🔴 / 🟡 / ❌-文案 / 命名漂移 / 边界漂移 汇总为**单一修正清单**，按"目标文件 + 修正项"组织：
+
+```markdown
+## 修正清单（请一次性确认；确认后我将批量更新三个文件）
+
+### prd.md
+1. **<需求点>**（Step 3 ❌ 曲解）: <原 PRD 内容> → <修正后内容>
+2. **<需求点>**（Step 3.5 🔴 缺失）: 补充章节 ... → <建议内容>
+3. ...
+
+### design.md
+1. **<设计单元>**（Step 4.1 ❌ 越界）: 删除 ... 段落
+2. **<设计单元>**（Step 4.2 🔴 漏覆盖）: 补充对应 <PRD AC>的设计
+3. **<命名漂移>**（Step 6.1）: 把 `user_id` 统一改为 `userId`（与 PRD 一致）
+4. ...
+
+### implement.md
+1. **<步骤>**（Step 5.1 ❌ 越界）: 删除 ... 步骤
+2. **<步骤>**（Step 5.2 🔴 漏落地）: 补充实现 <design 设计点> 的步骤
+3. **<文案漂移>**（Step 6.2）: 把按钮文字 `提交` 改为 `确认提交`（与 PRD 逐字一致）
+4. ...
+
+### 补任务建议（不在本任务范围）
+- <未覆盖的变更> — 建议挂到任务 <name> 或新建任务
+
+---
+
+**请回复"确认"批量执行，或指出需要调整的项。**
+```
+
+获得用户**单次"确认"**后，按清单批量修改三个文件，并在每个被修改文件的 Technical Notes / 变更日志末尾追加：
+
+```markdown
+> 修正于 YYYY-MM-DD HH:MM（trellis-verify-task）：<本次修正条目数概要>
+```
+
+> **不要**逐条问用户。**不要**先改 prd 再问后面要不要继续。一次给清单，一次确认，一次落盘。
+
+---
+
+## 反模式（避免）
+
+- ❌ 没有原始需求文档就凭感觉校验
+- ❌ 只看标题不看细节（AC 级别逐条对照）
+- ❌ 发现偏差不标记类型，笼统说"有出入"
+- ❌ 未经确认直接修改任何文件
+- ❌ **按层分次输出报告 / 分次请用户确认**（应一次出完整报告 + 一次性修正清单）
+- ❌ **校验时加入自己的"理解"和"建议"**（只对照，不发挥）
+- ❌ UI 文案不一致却只标记为 ⚠️ 措辞偏差（用户可见文案必须逐字一致，不一致直接标记 ❌）
+- ❌ 覆盖度扫描只看需求总表/目录，不扫描全文（嵌入式变更会遗漏）
+- ❌ 假设需求文档有固定的变更标记格式（每份文档结构可能不同）
+- ❌ 只追踪主需求单元，忽略同一功能点在其他页面/模块的散射变更
+- ❌ Lightweight 任务硬跑 Step 4 / 5 / 6（没有 design / implement 跑不了）
+- ❌ 把 Design / Implement 中的「实现必需」决策当作越界（凡标注了理由的"实现必需"都是合规的 🟡，不是 ❌）
+- ❌ 跨层一致性只校验三个 .md 中的两个（命名 / 文案 / 边界都必须三层全扫）
+
+---
+
+## 与其他入口的区别
+
+| 入口 | 形态 | 用途 | 时机 |
+|------|------|------|------|
+| `trellis-brainstorm` | skill（上游） | 从模糊想法对话生成 PRD（无原始文档时） | 需求讨论阶段 |
+| `trellis-extract-prd` | skill | 从原始需求文档**严格提取** PRD + task.json | 任务开发前、有正式需求文档时 |
+| `trellis-verify-task` | skill（本技能） | 校验任务三件套（prd / design / implement）准确性 + 覆盖度 + 跨层一致性 | 三件套生成后、开发前 |
+| `trellis-check-all` | skill | 代码实现对照三件套全面检查 | 编码完成后、提交前 |