flower-trellis 0.1.0

package/enhancements/0.5/.agents/skills/trellis-verify-prd/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: trellis-verify-prd
+description: "Audit prd.md against the original requirements doc (screenshots / tables / prose) via forward check (PRD→source) + reverse coverage scan (source→PRD); flag missing, misinterpreted, embellished, or UI-copy-mismatch items and propose edits. Triggers: 「校验 PRD」「对照原始需求」「verify PRD」. Not for PRD generation (trellis-brainstorm) or implementation-vs-PRD check (trellis-check-all)."
+---
+# 校验 PRD — 对照原始需求文档
+
+对照用户提供的原始需求文档（需求规格说明、PRD 截图、文字描述等），逐条校验生成的 `prd.md` 是否准确还原了原始需求，标记所有偏差并修正。同时扫描原始需求文档中的**所有本次版本变更内容**，检查是否存在被 PRD 遗漏的变更点。
+
+---
+
+## 核心原则（不可违反）
+
+1. **原始需求文档是唯一权威** — PRD 内容必须忠实反映原始需求，不得自行"理解"、"推演"或"发挥"
+2. **逐条对照，不跳不漏** — 原始需求的每一个条目都必须在 PRD 中找到对应描述
+3. **标记偏差类型** — 区分"缺失"、"曲解"、"发挥过度"、"措辞不准"
+4. **文案必须逐字一致** — 原始需求中出现的用户可见文案（按钮文字、提示语、Toast、弹窗内容、表头、placeholder 等）必须与 PRD **逐字一致**；文案不一致直接标记为 ❌ 曲解（不是 ⚠️ 措辞偏差），因为前端会照搬 PRD 文案实现
+5. **只改偏差，不改结构** — 修正内容错误，不改变 PRD 整体格式框架
+6. **版本变更全覆盖** — 原始需求中属于本次版本的所有变更内容都必须被某个任务/PRD 覆盖，不得遗漏
+
+---
+
+## 适用场景
+
+- PRD 刚生成（`trellis-brainstorm` 之后）尚未进入开发，需要对照原始需求文档做正反双向核对
+- 需求文档更新后，想确认 PRD 是否仍完整反映了最新版本的所有变更
+- 多任务 / 多 PRD 并行时，怀疑某次版本变更被漏挂到任何任务下
+
+---
+
+## 执行步骤
+
+### Step 1: 定位文件
+
+```bash
+# 获取当前任务
+python3 ./.trellis/scripts/task.py list
+```
+
+读取任务目录下的 `prd.md`。如果不存在，提示用户先创建。
+
+### Step 2: 获取原始需求文档
+
+**必须主动获取原始需求文档来源**。按以下优先级查找：
+
+1. **任务目录下的附件** — 检查任务目录下是否有 `requirements.md`、`spec.md`、`需求.md`、`*.xlsx`、`*.pdf` 等文件
+2. **PRD 中的引用链接** — 检查 PRD 中是否引用了外部文档链接
+3. **用户提供** — 如果上述都没有，**明确询问用户**：
+
+```markdown
+当前任务目录下未找到原始需求文档。请提供需求来源：
+
+1. **粘贴需求文本** — 直接粘贴原始需求内容
+2. **指定文件路径** — 告诉我需求文档在哪里
+3. **口述要点** — 口头说明关键需求点
+```
+
+> **[!] 严禁在没有原始需求文档的情况下进行校验** — 没有参照物的校验没有意义。
+
+### Step 3: 逐条对照
+
+将原始需求文档分解为独立条目（逐个需求点/AC/功能点），然后逐条在 PRD 中查找对应描述。
+
+对每一条标记状态：
+
+| 状态 | 含义 | 示例 |
+|------|------|------|
+| ✅ 准确 | PRD 忠实还原了原始需求 | — |
+| ⚠️ 措辞偏差 | 意思基本对，但措辞可能引起歧义 | 原始："下一行" → PRD："下一条未完结任务" |
+| ❌ 曲解 | PRD 理解错了原始需求的意思 | 原始："按当前列表排序" → PRD："按 taskNo 正序" |
+| ❌ 文案不一致 | UI 可见文案与原始需求不逐字一致（按钮、提示语、Toast、弹窗、表头、placeholder 等） | 原始：提示"确认提交？" → PRD："确认保存？" |
+| 🔴 缺失 | 原始需求有，PRD 里完全没提 | — |
+| 🟡 自行发挥 | PRD 写了原始需求没有的内容 | — |
+
+### Step 3.5: 覆盖度扫描（反向检查）
+
+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 中有对应，但该单元内的某些变更点未被提及 |
+
+> **特别注意散射型变更**：同一个功能点可能散布在多个需求单元中。
+> 即使主需求已覆盖，也要检查所有关联位置。
+
+#### 3.5.4 输出覆盖度清单
+
+对未覆盖和部分覆盖的变更，列出详情供 Step 4 报告使用。
+
+---
+
+### Step 4: 输出校验报告
+
+```markdown
+## PRD 校验报告
+
+### 任务: <任务名称>
+
+### 一、准确性校验
+
+#### 总览
+- 原始需求条目数: N
+- ✅ 准确: X 条
+- ⚠️ 措辞偏差: X 条
+- ❌ 曲解: X 条
+- 🔴 缺失: X 条
+- 🟡 自行发挥: X 条
+
+#### 逐条对照
+
+##### <需求点 1 标题>
+- **原始需求**: <原文摘抄>
+- **PRD 描述**: <PRD 中的对应内容>
+- **状态**: ✅ / ⚠️ / ❌ / 🔴 / 🟡
+- **问题**: <如果有偏差，说明具体问题>
+- **建议修正**: <如果需要修正，给出建议>
+
+##### <需求点 2 标题>
+...
+
+---
+
+### 二、覆盖度扫描
+
+#### 总览
+- 原始文档版本变更总数: N
+- ✅ 已覆盖: X 个
+- 🔴 未覆盖: X 个
+- ⚠️ 部分覆盖: X 个
+
+#### 未覆盖的变更点
+
+| 需求单元 | 位置 | 变更内容摘要 | 影响范围 |
+|---------|------|-------------|---------|
+
+#### 部分覆盖的变更点
+
+| 需求单元 | 位置 | 变更内容摘要 | PRD 中已有的覆盖 | 缺失的部分 |
+|---------|------|-------------|----------------|-----------|
+
+---
+
+### 三、结论
+- <总结性评价>
+- <准确性是否需要修正>
+- <覆盖度缺口是否需要补充任务>
+```
+
+### Step 5: 修正 PRD（需用户确认）
+
+如果发现偏差，**先列出所有修正项，获得用户确认后再修改 `prd.md`**。
+
+```markdown
+以下是建议的修正项：
+
+1. **<需求点>**: <原 PRD 内容> → <修正后内容>
+2. ...
+
+确认后我将更新 prd.md。
+```
+
+修正时遵循：
+- **只改内容偏差，不改 PRD 格式**
+- **优先使用原始需求文档的原文措辞**
+- **标注修正来源**：在 Technical Notes 中记录本次校验
+
+---
+
+## 反模式（避免）
+
+- ❌ 没有原始需求文档就凭感觉校验
+- ❌ 只看标题不看细节（AC 级别逐条对照）
+- ❌ 发现偏差不标记类型，笼统说"有出入"
+- ❌ 未经确认直接修改 PRD
+- ❌ 校验时加入自己的"理解"和"建议"（只对照，不发挥）
+- ❌ UI 文案不一致却只标记为 ⚠️ 措辞偏差（用户可见文案必须逐字一致，不一致直接标记 ❌）
+- ❌ 覆盖度扫描只看需求总表/目录，不扫描全文（嵌入式变更会遗漏）
+- ❌ 假设需求文档有固定的变更标记格式（每份文档结构可能不同）
+- ❌ 只追踪主需求单元，忽略同一功能点在其他页面/模块的散射变更
+
+---
+
+## 与其他入口的区别
+
+| 入口 | 形态 | 用途 | 时机 |
+|------|------|------|------|
+| `trellis-brainstorm` | skill | 从模糊想法生成 PRD | 需求讨论阶段 |
+| `trellis-verify-prd` | skill（本技能） | 对照原始需求文档校验 PRD（准确性 + 覆盖度） | PRD 生成后、开发前 |
+| `trellis-analyze-task` | skill | 分析任务可行性和风险 | 开发前 |
+| `trellis-check-all` | skill | 代码实现对照 PRD 全面检查 | 编码完成后、提交前 |

package/enhancements/0.5/.claude/skills/trellis-analyze-task/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: trellis-analyze-task
+description: "Analyze and refine an existing task under .trellis/tasks/: read task.json + prd.md + related code, output scope/risks/ambiguities report, then ask clarifying questions one at a time to update prd.md/task.json in real-time. Triggers: 「分析任务」「细化任务」「这个任务怎么做」. For brand-new features without a task yet, use trellis-brainstorm."
+---
+# 任务深度分析与细化
+
+对 `.trellis/tasks/` 下的已有任务进行深入分析，提供全景预览、识别风险点，并通过交互式问答细化任务内容。
+
+---
+
+## 适用场景
+
+- 已有 task 但需求不够清晰，需要拆解成可执行步骤
+- 任务拿到后还不确定影响面、风险点或不明确处
+- 开发前的深度细化环节
+
+---
+
+## 执行步骤
+
+### Step 1: 定位任务
+
+参数：`task-slug`（可选）。提供时直接定位，未提供时列出所有活跃任务让用户选择。
+
+```bash
+# 未指定任务时，列出所有活跃任务
+python3 ./.trellis/scripts/task.py list
+```
+
+- 如果用户未指定任务，展示任务列表并用 `AskUserQuestion` 让用户选择
+- 定位后，读取任务目录下的 `task.json` 和 `prd.md`（如果存在）
+
+### Step 2: 上下文收集（静默执行，不问用户）
+
+在分析之前，自动收集信息：
+
+1. **任务文件**：读取 `task.json`、`prd.md`（如果有）
+2. **相关代码**：如果任务涉及具体模块，快速扫描相关代码结构
+3. **依赖任务**：检查是否有关联或依赖的任务
+4. **历史记录**：检查 journal 中是否有该任务的相关记录
+
+### Step 3: 输出分析报告
+
+以下列结构输出分析报告：
+
+```markdown
+## 任务分析报告: <任务标题>
+
+### 概述
+<用 2-3 句话总结这个任务要做什么、为什么要做>
+
+### 工作预览
+预计需要做的事情：
+1. <步骤 1>
+2. <步骤 2>
+3. ...
+
+### 涉及范围
+- **模块/文件**: <涉及哪些模块或文件>
+- **影响面**: <这个变更会影响到什么>
+- **依赖**: <需要什么前置条件>
+
+### 风险点
+1. <风险 1>: <说明 + 可能的后果>
+2. <风险 2>: <说明 + 可能的后果>
+
+### 不明确的地方
+1. <问题 1>: <为什么这个需要澄清>
+2. <问题 2>: <为什么这个需要澄清>
+
+### 建议
+- <可选的改进建议或替代方案>
+```
+
+### Step 4: 交互式反问
+
+报告输出后，**逐个**向用户提出不明确的问题（每次只问一个）。
+
+使用 `AskUserQuestion` 工具提问，优先提供选项：
+
+```markdown
+关于 <问题主题>，你倾向于哪种方式？
+
+1. **选项 A** — <含义 + 利弊>
+2. **选项 B** — <含义 + 利弊>
+3. **其他** — 你来说明
+```
+
+### Step 5: 根据反馈更新任务
+
+每收到一个回答后：
+1. **立即更新** `prd.md`（如果存在）或创建新的 `prd.md`
+2. **更新** `task.json` 中的相关字段（如优先级、描述等）
+3. 继续下一个问题，直到所有不明确的地方都澄清
+
+### Step 6: 输出细化结果
+
+所有问题回答完毕后，输出最终的细化摘要：
+
+```markdown
+## 任务细化完成
+
+### 变更摘要
+- <列出 prd.md / task.json 的变更内容>
+
+### 下一步
+- 如果准备开发：运行 `trellis-continue` 进入/继续开发流程
+- 如果需要进一步讨论：继续对话
+```
+
+---
+
+## 核心原则
+
+| 原则 | 说明 |
+|------|------|
+| **先分析后提问** | 先展示你的分析和理解，再提问 |
+| **每次只问一个问题** | 不要用问题列表轰炸用户 |
+| **提供选项** | 尽量给出可选方案而非开放式问题 |
+| **即时更新** | 每次收到回答立即更新文档 |
+| **识别真正的风险** | 区分「可能的风险」和「确定的风险」 |
+| **YAGNI** | 挑战不必要的复杂度，聚焦真正需要的 |
+
+---
+
+## 与其他入口的区别
+
+| 入口 | 形态 | 用途 | 输入 |
+|------|------|------|------|
+| `trellis-brainstorm` | skill | 从模糊想法出发，发现需求 | 用户的初始想法（尚无 task） |
+| `trellis-analyze-task` | skill（本技能） | 对已有任务深入分析和细化 | 已存在的 task |
+| `trellis-continue` | 命令 | 进入/继续开发流程 | 已有 prd.md 的任务 |
+
+---
+
+## 反模式（避免）
+
+- ❌ 直接输出一大堆问题让用户回答
+- ❌ 不看代码就做分析（先收集上下文）
+- ❌ 分析报告过于笼统（要具体到文件和模块）
+- ❌ 过度细化不重要的细节
+- ❌ 忽略跨模块影响

package/enhancements/0.5/.claude/skills/trellis-check-all/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: trellis-check-all
+description: "Full pre-commit/PR review in 3 steps: PRD-implementation correctness → 5-dim assumption validation (API, component context, data history/flow, tests) → cross-layer completeness + spec compliance (delegates to trellis-check). Pauses on ❌. Triggers: 「全面检查」「提交前检查」「check-all」「从 PRD 到代码过一遍」. For lint/spec-only, use trellis-check directly."
+---
+# Check All — 全维度代码检查
+
+依次执行三个维度的代码检查，一次性完成全维度质量验证。
+
+> 顺序逻辑：**正确性 → 假设验证 → 完整性+规范性**
+> 先保证"做对了"，再保证"做全了"，最后保证"写好了"。
+
+---
+
+## 执行模式
+
+**各 Step 的具体 check 在主对话中直接展开执行，不要用 Agent 工具委派给子 agent 跑。**
+
+原因：
+- 各 Step 中存在"发现问题立即暂停询问用户"的交互点，子 agent 无法交互式暂停
+- 检查结果的具体细节（哪一行、哪个假设错了）对后续修复很关键，子 agent 的摘要式返回会丢失细节
+
+**例外**：仅当用户显式要求"用子 agent 跑各 Step"或"并行执行"时，才使用 Agent 工具委派。
+
+---
+
+## 三个维度（按顺序执行）
+
+| 顺序 | 维度 | 检查什么 | 对照物 |
+|------|------|---------|--------|
+| 1 | PRD 实现 | 实现对不对 | PRD |
+| 2 | 假设验证 | 假设对不对 | 源码/真实数据 |
+| 3 | 完整性+规范性（trellis-check） | 改全了没 + 写得规范吗 | git diff 影响范围 + spec 开发规范 |
+
+---
+
+## Step 0: 确认变更范围
+
+```bash
+git diff --name-only
+git log --oneline -10
+```
+
+如果无变更，提示用户并终止。
+
+读取当前任务的 `prd.md`（由 trellis 的 session hook 自动加载，或手动确认任务目录）。如果没有 PRD，跳过 Step 1 从 Step 2 开始。
+
+---
+
+## Step 1: 对照 PRD 检查实现
+
+**重点**：PRD 中的每条需求和 AC 是否都正确实现了？有没有行为偏差、功能缺失、文案不一致？
+
+### 1.1 核心原则（不可违反）
+
+1. **PRD 是验收标准** — 每条 Requirement 和 AC 都必须在代码中找到对应实现，找不到即为缺失
+2. **逐条追踪，不跳不漏** — 不能只看 happy path，PRD 中提到的边界条件、异常处理、空值场景都要追踪
+3. **读代码，不猜代码** — 必须实际读到实现代码，不能因为"应该写了"就标记通过
+4. **文案逐字比对** — PRD 中的 UI 文案（按钮、提示语、Toast、弹窗、表头、placeholder）必须与代码中的字面值**完全一致**
+5. **只报事实，不加发挥** — 报告中只陈述 PRD 要求 vs 代码实现的差异，不要加入 PRD 之外的建议
+
+### 1.2 分解 PRD 为可验证条目
+
+从 PRD 中提取（按优先级）：
+1. **Acceptance Criteria** — 最直接的验证条目
+2. **Requirements** — 每条需求对应的行为
+3. **业务规则** — 条件判断、计算逻辑、状态流转
+4. **UI 文案** — 所有用户可见文字
+5. **边界/异常场景** — 空值处理、上限、错误提示等
+
+每条记录格式：`[条目ID] <PRD 原文摘要> — 来源：<PRD 中位置>`
+
+### 1.3 逐条追踪代码实现
+
+根据条目类型定位实现：
+
+| 条目类型 | 搜索方法 |
+|---------|---------|
+| API 接口行为 | Controller → Service → DAO，追踪完整链路 |
+| 前端交互行为 | 组件文件，事件处理、状态管理 |
+| 数据校验规则 | 前端 rules + 后端 validator/service，两端都查 |
+| UI 文案 | grep 关键字，前端代码精确匹配 |
+| 计算/转换逻辑 | service 层，读具体算法 |
+| 状态流转 | 状态枚举 + 转换条件代码 |
+
+对每条标记状态：
+
+| 状态 | 含义 |
+|------|------|
+| ✅ 已实现 | 代码正确实现了 PRD 要求（已读代码确认） |
+| ❌ 实现偏差 | 代码实现了，但行为与 PRD 描述不一致 |
+| 🔴 未实现 | 代码中找不到对应实现 |
+| ⚠️ 部分实现 | 核心逻辑有，但缺少边界/异常处理 |
+| 🟡 文案不一致 | UI 文案与 PRD 不逐字一致 |
+
+### 1.4 重点检查场景（最容易漏）
+
+- **条件判断** — PRD 说"当 X 时做 Y"，if 条件是否完整？是否漏边界值？
+- **空值/零值** — PRD 提到的字段，代码在该字段为空时是否有处理？
+- **列表为空** — 列表展示是否有空状态/提示？
+- **并发/时序** — 多步操作是否处理了中间状态？
+- **权限控制** — PRD 提到的按钮/操作，是否加了权限判断？
+- **前后端一致** — 同一条规则前后端是否都实现了？
+
+### 1.5 问题记录模板
+
+发现问题时按如下格式逐条记录（供最终汇总报告引用）：
+
+**❌ 实现偏差 / 🔴 未实现 / ⚠️ 部分实现**：
+
+```markdown
+##### [条目ID] <PRD 原文摘要>
+- **PRD 要求**：<原文>
+- **实际实现**：<代码行为描述>
+- **代码位置**：<文件路径:行号>
+- **偏差/缺失说明**：<具体差异或缺失点>
+```
+
+**🟡 文案不一致**（用表格汇总）：
+
+| PRD 文案 | 代码文案 | 代码位置 |
+|---------|---------|---------|
+
+> **如果发现 ❌ 实现偏差或 🔴 未实现，立即暂停**，展示问题并询问用户：
+> - 先修复再继续后续检查？
+> - 还是先跑完全部检查，最后统一修复？
+
+---
+
+## Step 2: 实现假设验证
+
+**重点**：API 响应结构、组件生命周期、历史数据兼容性等假设是否正确？大多数实现 bug 不是逻辑错误，而是前提假设错了。
+
+根据变更类型选择适用的 Dimension 检查：
+
+### Dimension A: API Contract（调用了已有 API 时）
+
+**Trigger**：前端新增/修改了对后端 API 的调用
+
+**Checklist**：
+- [ ] 读过 Controller/Handler 源码，确认实际响应结构？
+- [ ] 找到项目中已有的同 API 调用代码作为参考？
+- [ ] 请求参数名、类型、默认值从源码确认（非凭记忆）？
+- [ ] 分页接口：确认了分页字段名和起始页码？
+
+**典型错误假设**：
+
+| 错误假设 | 实际情况 |
+|---------|---------|
+| `res.data.data` 是数组 | 实际是 `{ items: [], total }` 分页结构 |
+| 参数名是 `page` | 实际是 `p`，且从 1 开始 |
+| 响应直接是业务数据 | 实际包了一层 `{ success, message, data }` |
+
+### Dimension B: Component Context（在容器内使用组件时）
+
+**Trigger**：在 Modal / Drawer / Tab / 条件渲染块内使用有状态组件
+
+**Checklist**：
+- [ ] 确认容器关闭/切换时是否销毁子组件？
+- [ ] 如需保持状态：是否用了 keepDOM / destroyOnClose={false} 等配置？
+- [ ] 受控组件的 value 与外部 state 是否正确绑定？
+- [ ] 找到项目中同容器内的组件用法作为参考？
+
+**典型错误假设**：
+
+| 错误假设 | 实际情况 |
+|---------|---------|
+| Modal 关闭后表单状态保留 | 默认销毁子组件，再开状态丢失 |
+| value 传了就是受控 | 某些组件需 initValue + value 配合 |
+| 组件在任何地方行为一致 | 容器上下文会影响挂载/卸载行为 |
+
+### Dimension C: Data History（修改了数据模型时）
+
+**Trigger**：数据库表新增/修改了字段
+
+**Checklist**：
+- [ ] 历史记录的新字段值是什么（空/零值/null）？
+- [ ] 用新字段过滤时，历史数据能否被正确查到？
+- [ ] 是否需要降级查询路径（如从其他表补查历史数据）？
+- [ ] 写入链路中新字段的值从哪来？来源是否可靠？
+
+**典型错误假设**：
+
+| 错误假设 | 实际情况 |
+|---------|---------|
+| 加了字段就有数据 | 旧记录新字段全是零值/空值 |
+| 只查聚合表就够了 | 聚合表缺维度，需从明细表降级查询 |
+| 字段值肯定有 | 某些调用链路中该值可能为空 |
+
+### Dimension D: Data Flow Trace（跨层变更时）
+
+**Trigger**：变更涉及 前端 ↔ API ↔ 数据库 的数据传递
+
+**Checklist**：
+- [ ] 模拟一条完整请求路径：前端发什么 → 后端收什么 → 查出什么 → 返回什么 → 前端解析什么？
+- [ ] 前端参数名 === 后端 Query/Body 参数名？
+- [ ] 后端返回结构 === 前端解析结构？
+- [ ] 空值/零值场景：不填该字段时，每一层的行为是否正确？
+
+**典型错误假设**：
+
+| 错误假设 | 实际情况 |
+|---------|---------|
+| 代码看起来对就能跑 | 参数名差一个字母、嵌套差一层 |
+| 只检查非空路径 | 空值路径才是出 bug 最多的地方 |
+| 前后端分别看都没问题 | 放一起跑时数据对不上 |
+
+### Dimension E: Verification Tests（验证关键假设的测试）
+
+**Trigger**：任何涉及 Dimension A-D 的变更
+
+光靠肉眼审查不够，关键假设必须有可运行的验证手段：
+
+- **API Contract 验证**：写请求测试验证实际响应结构与解析匹配，覆盖 happy + 空值/零值
+- **数据模型验证**：用真实数据（含历史旧记录）验证过滤/聚合结果
+- **跨层数据流验证**：端到端测试完整路径，覆盖空参数、特殊字符、零值
+
+**验证原则**：
+- 不要求高覆盖率，但每个 Dimension 中发现的关键假设至少有一个测试保护
+- 优先写能暴露"想当然"问题的测试，而非走过场的 happy path
+- 如果无法写自动化测试，记录手动验证步骤和预期结果
+
+**典型错误做法**：
+
+| 错误做法 | 正确做法 |
+|---------|---------|
+| 只写 happy path 测试 | 优先覆盖假设最脆弱的路径 |
+| 测试写了但没跑 | 测试必须实际运行并通过 |
+| "这个太简单不用测" | 越简单的假设越容易错（参数名、嵌套层级） |
+
+### Common Issues Quick Reference（假设类 bug 速查）
+
+| Issue | Root Cause | Prevention |
+|-------|------------|------------|
+| API 调用返回 undefined | 响应结构假设错误 | 读 Controller 确认 |
+| 组件状态莫名丢失 | 容器销毁了子组件 | 检查容器生命周期 |
+| 筛选后数据为空 | 历史记录缺字段 | 验证旧数据查询路径 |
+| 参数传了但后端没收到 | 参数名不匹配 | 源码级确认参数名 |
+| 看着对但跑不通 | 只做了静态审查 | 模拟完整数据流 |
+
+> **如果发现假设错误**，同样立即暂停询问用户（先修复 or 跑完再统一修）。
+
+---
+
+## Step 3: 跨层完整性与代码规范检查
+
+按 `.agents/skills/trellis-check/SKILL.md` 执行。
+
+**重点**：变更涉及的所有层、所有引用点是否都同步更新了？代码是否符合项目 spec 中的编码规范？lint 和 typecheck 是否通过？
+
+---
+
+## 输出：汇总报告
+
+所有检查完成后，输出一份汇总报告：
+
+```markdown
+## Check All 汇总报告
+
+### 任务: <任务名称>
+
+---
+
+### 各维度结果
+
+| 维度 | 状态 | 问题数 | 关键问题 |
+|------|------|--------|---------|
+| PRD 实现 | ✅/❌ | N | <最严重的问题摘要> |
+| 假设验证 | ✅/❌ | N | <最严重的问题摘要> |
+| 跨层完整+规范 | ✅/❌ | N | <最严重的问题摘要> |
+
+### 问题清单（按优先级排序）
+
+#### P0 — 功能性 BUG（来自 Step 1 / Step 2）
+<PRD 实现偏差 / 🔴 未实现 / 假设错误>
+
+#### P1 — 完整性+规范问题（来自 Step 3）
+<跨层遗漏 / lint / typecheck / 规范违反>
+
+### 结论
+- <总体评价：整体完成度>
+- <建议修复顺序：P0 先修，P1 可视情况合并修>
+```
+
+---
+
+## 修复问题（需用户确认）
+
+如果发现问题，**先展示报告，获得用户确认后再修复**。
+
+修复时遵循：
+- **按严重程度排序**：❌ 实现偏差 > 🔴 未实现 > ⚠️ 部分实现 > 🟡 文案不一致 > P1 完整性/规范
+- **每修一条标注 PRD 条目 ID 或问题位置**
+- **修复后重新验证该条目**
+
+---
+
+## 使用时机
+
+- **开发完成后、提交前** — 作为 `trellis-finish-work` 之前的全面检查
+- **Code Review 前** — 自查一遍再提交 MR
+- **不确定改动质量时** — 跑一遍全量检查心里有底
+
+---
+
+## 注意事项
+
+- 每个维度独立输出报告，最后汇总
+- 如果某个维度发现严重问题（❌ / 🔴），会暂停询问是否先修复
+- 如果当前任务没有 PRD，自动跳过 Step 1，从 Step 2 开始
+- 只想快速检查某一维度：
+  - 只查规范/跨层：直接用 `trellis-check` skill
+  - 只查 PRD 或假设：在 prompt 里指定"只做 Step 1"或"只做 Step 2"
+
+---
+
+## 反模式（避免）
+
+- ❌ 不读代码，凭"应该实现了"就标记通过
+- ❌ 只检查 happy path，忽略 PRD 提到的边界/异常场景
+- ❌ 文案只看"意思对"就通过（必须逐字一致）
+- ❌ 只查后端不查前端，或反之
+- ❌ 检查报告中加入 PRD 之外的改进建议（只对照 PRD，不发挥）
+- ❌ 发现问题直接改，不经用户确认
+- ❌ 委派给子 agent 跑各 Step（见执行模式段）