@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/review-prd/references/review-lenses.md

@@ -0,0 +1,82 @@
+# 四个 PRD 审查视角
+
+Reviewer 读自己的节；跨视角复核再读关联节。按本次产品范围裁剪检查深度，不能用一张通用清单制造功能或阻塞。
+
+## A. facts：核实代码现状与前置
+
+先把关键主张分成现状、未来能力、约束、假设、验收目标。事实核实优先覆盖会改变范围、产品形态、权限、兼容、质量或依赖的陈述。
+
+### 从文件存在追到实际行为
+
+1. 用 `rg --files` / `rg` 定位声明和真实调用者，读取相关入口、授权、业务实现、返回/状态展示及必要配置。文件名、路由、类型或函数存在，只能证明那个入口存在，不能证明已经满足用户场景。
+2. 按 PRD 依赖的行为追踪：谁能发现/执行、输入边界、状态迁移、结果是否可消费、错误/降级、重复与冲突、分页与规模、跨租户/用户边界。发现对应测试时读其断言和替身，区分真实行为与 mock 假设；未执行测试不写「测试通过」。
+3. 核实可复用依赖的契约、权限、配置和目标环境：可检索不等于可安装，HTTP 入口不等于支持 Agent 原生消费，模型网关存在不等于当前应用/主体可调用，前端隐藏按钮不等于后端拒绝越权。
+4. 声称「不存在」时说明检查过的目录/入口/配置和搜索范围，必要时跟踪动态注册或外部服务。仅未搜到关键词只能写「在已查范围未定位」，不能断言整个系统没有能力。
+5. 声称已验证兼容、性能、UI 或生产可用时核对实际环境、版本与记录。当前源码存在、历史计划完成、SPMS 状态与生产部署不是同一事实。没有部署证据不推断线上版本；没有有效测量不声称达到门槛。
+6. 数字、业务规则和平台约束给来源；区分代码现状与规范要求。两者冲突就同时定位，不因代码不同自动废除约束。旧文档/README/记忆仅是线索，不代替本次行为核实。
+7. 涉及当前生态支持、版本能力或外部限制时先读依赖/配置，再查官方文档或一手来源，保留版本、日期与链接。不能访问就标具体待核实项，不以记忆冒充最新结论。
+
+### 现状核实矩阵
+
+| PRD 主张/定位 | 类型 | 代码现状及证据等级 | 与目标的关系 | 产品影响/所需补证 |
+| --- | --- | --- | --- | --- |
+| <已有能力/可复用/未支持等陈述> | <现状/目标/约束/假设> | <路径:行号/符号;源码核实/测试记录/实测/未核实> | <已有满足/部分满足/真实增量/行为冲突/未核实> | <改正背景、明确增量、补前置/决策/证据> |
+
+「真实增量」仅表示本次已查实现不具备目标能力，不表示 PRD 有缺陷。「已有满足」也不自动撤回需求，可能仍需要新的可用性、质量或治理边界。用户已明确不考虑存量时尊重该选择，不强加迁移兼容；其他产品前置仍须核实。
+
+已有代码缺陷只有被本 PRD 依赖、放大或直接阻断目标时进入评审；无关代码问题不扩展成本次代码审计。源码不可访问时交付明确的核实清单与证据缺口，继续其他维度；不能冒充已核实或直接判依赖不存在。
+
+## B. product：创新、先进性、AI 与范围
+
+从用户问题推导价值，检查采用的选择是否在约束内把任务设计充分。先进性以用户收益、质量和合理成本判断，技术新旧、术语数量或功能多少不自动加分。
+
+- 是否仅转录功能清单，遗漏完成关键任务必须的发现、理解、决策、使用与维护环节？是否有比照搬现状/参考项目更有价值的产品形态？指出具体场景、收益与取舍，不能只写「不够创新」。
+- 参考产品、官方生态能力是否适配目标用户、租户、身份和使用环境？区分声明、已核实能力和拟新增能力，避免承诺未经验证的兼容组合。
+- AI 能改善发现、理解、创作、决策或重复劳动时是否有合理方案？未采用但有充分理由则可接受；没有 AI 不自动算缺陷，用户排除或价值不足时不强加。
+- 已采用 AI 是否有明确任务、触发、授权输入、可用输出、依据/不确定性、用户采纳/修改/拒绝/撤销、质量口径、成本与不可用状态？辅助 AI 不可用时基本任务能否继续；AI 是核心时是否如实进入等待/失败，而非虚假成功？
+- 原始诉求、目标、范围、非目标及决策是否一致？终局是在本 PRD 范围内充分设计，不是整个产品无限扩张。PoC 说明要证明的假设及成立判据，不能自动扩成完整系列，也不能仅罗列技术组件。
+- 是否把怎么实现混进产品决策？内部架构、表/端点设计、算法/模型选型移交开发计划；已给定约束和外部可消费契约保留必要产品语义。
+
+交回：`产品选择 | 用户价值/目标 | 依据与约束 | 取舍/不足 | 必要修订或非阻塞机会`。遗漏机会只有在直接影响已确认目标、且收益和适配有依据时才作为缺陷；其他合理改进单列提案，不能未经确认写成承诺。
+
+## C. experience：可用、便捷与美观 UI
+
+逐角色走主旅程：`找到入口 → 理解信息/条件 → 完成任务 → 确认结果 → 再次使用或失败恢复`。无 UI 产品仍走调用方/Agent/运维的相应消费旅程，可用性不能随 UI 一起跳过。
+
+- 主路径是否能完成端到端任务，而不是只有数据、API 或几个按钮？用户是否被迫理解内部术语、反复输入信息、切换入口或自行补步骤？首次与高频路径是否合适？
+- 相关的等待、空数据、无权、错误、部分成功、重复/冲突、取消及恢复是否状态清楚、结果真实、下一步可行动？角色与权限改变不能只靠前端隐藏。
+- 默认信息、主操作和信息层级是否支持任务；细节是否渐进展示；风险和必要前置是否始终足够可见？
+- 美观是否落实为信息主次、排版、密度、留白、视觉语言与宿主一致性；是否只写「现代 UI」或仅有可访问性指标？适用的窗口、主题、语言、键盘/焦点、对比度等是否有产品要求与验收？
+- 区分产品交互与实现：一次引用跳转、状态反馈、可撤销操作属于 PRD；组件库、CSS/DOM 与焦点代码的实现不应被强制补进 PRD。
+
+| 实际材料 | 支持的结论 | 必须说明的限制 |
+| --- | --- | --- |
+| PRD/流程/源码 | 任务闭环、规则与交互要求的合理性 | 文档/静态代码推演，不能证明美观或真实交互通过 |
+| 设计稿/截图 | 可见布局、信息层级与视觉一致性 | 静态评审，不能证明操作和权限行为 |
+| 已授权的原型/浏览器实测 | 本次实际观察的旅程、状态与视觉 | 记录环境/版本/场景/结果；没有走过的路径仍未验证 |
+
+没有实现页面不自动阻塞 PRD；关键在产品状态与验收是否已定清。现有页面可安全只读走查时按目标仓浏览器工作流采集证据，不为评审改动真实业务数据。UX findings 写清哪个角色在什么任务中被怎样阻碍，不能把个人审美偏好当缺陷。
+
+## D. acceptance：SMAR、UAT 与分期终验
+
+SMAR 检查目标与需求：
+
+| 原则 | 核对要点 |
+| --- | --- |
+| Specific | 角色、对象、场景、作用域、权限与能力边界明确，领域词和状态语义一致 |
+| Measurable | 预期状态可判断；数值有作用域/负载/样本/分母/窗口，明确枚举、是/否、相等/不变也合格 |
+| Actionable | 用户或授权主体能执行具体业务动作，得到可用结果；不只写愿景或技术名词 |
+| Reasonable | 价值、质量、成本、依赖及支持范围与用户约束相容，未知前置没有被写成无条件承诺 |
+
+区分验收门槛、上线观察指标与 PoC 比较基线；建议数值不能冒充已实测结果。不用 Time-bound 编造工期，已有外部日期、性能时延、超时、有效期及观察窗口仍有效。
+
+双向追踪：`原始诉求/目标 → 场景 → FR/NFR → 验收 → UAT 预期状态 → 分期/终验`。
+
+- 每个目标有需求承接，每个重要用户场景有预期状态与通过条件，每条完整能力有可判断的验收。UAT 应描述结果是否可用、反馈、下一步及数据变化，不只是一条提示文案。
+- 成功与本产品相关的空、拒绝、冲突、取消、失败/恢复和 AI 不确定/降级场景有清晰结果。不能到测试计划阶段才决定产品状态，也不能把造数、脚本、探针、故障注入当 UAT 内容。
+- 没有 TC、没有 SPMS key、章节不同本身不算缺陷。真实 key 不可伪造；缺少验收语义才是问题。代码/设计内部断言若无法表达外部结果，要求改为业务边界，不要求 PRD 拟写测试过程。
+- 每期有独立用户价值、范围与出口判据，不按前后端技术栈切期。终局需求不因交付节奏被删小，非目标不充当延期列表；已明确的其他 PRD 分工可作为范围去向。
+- 每期开发计划尽量 5–8 个 Milestone；连续性例外 9–10 个说明理由，最多 10 个；小范围可以更少，不凑数。这里只检查规模预算，详细任务和准确拆解由 dev-plan 核实，超出则反馈拆期。
+- 逐条核对分期验收分配和最终完成期；跨期条目正文、分期矩阵及已录入系统的终验声明口径一致。部分交付不能被标成整条完成，前置条件不归本 PRD 的不得被默默视为已就绪。
+
+交回断链 ID/章节、相互矛盾的两处、受影响用户场景与最小产品修订。不能因没有开发计划的技术里程碑而判 PRD 不可行动。

package/skills/review-prd-dev-gaps/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: review-prd-dev-gaps
+description: 接受 PRD 与已完成的开发计划，追读里程碑完成记录并核对实际实现，将差异分为明确遗漏、合理变更和需用户 Triage 的实现差异；通过交互式问答确定处置，有 follow-up 时调用 dev-plan 创建 gaps plan。用于开发完成后的需求覆盖核查，不用于评审 PRD 质量、计划设计或单次代码 diff。
+---
+
+# review-prd-dev-gaps · PRD 与开发交付差异核查
+
+目标：回答 **PRD 要求的能力实际上交付了什么，哪些漏做了，哪些调整有充分依据，哪些差异需要用户拍板，以及还要补什么。** 以 PRD 建立完整覆盖账本，以计划、完成记录和实际行为交叉核实，不把「计划已完成」等同于「PRD 已实现」。
+
+默认交付完整差异报告；存在应跟进事项时，再实际调用 `dev-plan` 产出独立 gaps plan。`references/` 相对本文件解析，回复语言跟随用户。
+
+## 边界
+
+- 输入为 PRD、已完成开发计划及其引用的完成记录；代码仓、测试、运行证据和历史决策用于核实。目标无法唯一确定时询问文档/仓库位置，先做不依赖该信息的调查，不擅自选择相邻文档。
+- 默认只写差异报告和新 gaps plan。原 PRD、原计划、完成记录和代码保持只读；文档同步也列为 follow-up，不自动修改历史完成事实。不自动实施、创建 issue、发布或发送评论。
+- 只核对 PRD 及已确认变更承诺的范围，不新增产品机会，不设问题数量或 top-N 截断。明确不在本期的需求保留追踪去向，不当成本期遗漏；未获确认的删减/延期不能算范围外。
+- 参考 `gen-specs-as-issues` 的文档对照实际行为、用户旅程和依赖分析思路，不继承其问题配额、评分公式或 issue 创建流程；运行时不依赖该参考技能。
+
+## 1. 锚定输入与证据链
+
+1. 读取适用仓库规则，记录审查日期、PRD/计划路径及版本或 hash、代码仓 commit/dirty 状态、目标阶段和验收环境。当前工作树参与调查时明确标注；不能把开发分支通过当成已经上线。
+2. 通读 PRD 与开发计划，提取原始需求 ID、用户场景、业务规则、权限、FR/NFR、验收/UAT、分期和显式排除。无 ID 时使用稳定章节定位；仅为审查拆出的子项标明是本报告编号，不冒充源需求。
+3. 沿计划的记录索引读取各里程碑完成记录，包括测试结果、已知限制、未完成项、延期和实现变更；按需追读其指向的验收报告、ADR 或用户决定。相对链接按所属文档目录解析。记录缺失、链接不可访问或内容截断时标出缺口，不推断其中内容。
+4. 核对完成声明与记录：里程碑退出条件、跳过/失败测试、局部验收与阶段终验是否一致。原计划实际未完成时说明输入前提不成立，继续核对可确认部分，不能把未完成项包装成「完成后新发现」的遗漏。
+5. 读取 [references/report-contract.md](references/report-contract.md)，确定报告路径，建立 `PRD → 计划/里程碑 → 完成记录 → 实际行为/验证` 的追踪账本。**从 PRD 向下追踪**，防止只审计划已有条目而漏掉从未进入计划的需求。
+
+## 2. 核实功能实现情况
+
+- 每个在范围内的需求/验收条件都要有覆盖行。一个需求部分满足时拆出未满足条件，不用已实现的主路径掩盖权限、异常、状态反馈或边界行为的缺口。跨里程碑能力检查最终用户旅程，不能只拼接各局部的完成声明。
+- 追到可观察行为：入口与权限 → 业务处理/依赖 → 数据或状态变化 → 用户/调用方结果；按该需求检查配置开关、部署条件和真实接线。文件存在、类型定义、占位代码、mock、不可达入口不等于交付。
+- 完成记录是证据线索，不是免检证明。区分「文档自述」「静态代码核实」「已有测试/运行记录」「本次实际验证」，注明环境、版本及适用范围；未运行测试就不能说本次通过。性能、视觉、端到端可用性等结论必须有相应证据。
+- 报「不存在」前，调查真实入口、同义实现、复用能力、配置及替代路径；一次关键词未命中不足以证明遗漏。只在授权范围运行必要验证，不能执行迁移、部署或有副作用的业务操作来凑证据。
+- 证据不足时，先查能查的事实，再列具体补证方式。无法访问代码/环境时继续文档级核对，保留未核实状态，不把整份 PRD 宣称已实现，也不把所有未知都报成遗漏。
+
+## 3. 将实质差异分为三类
+
+每项差异用稳定 `G-01` 等编号，记录 PRD 期望、实际行为、影响、来源和分类依据。已满足/范围外是覆盖状态；待核实是证据状态，均不是第四类差异结论。证据未足够时分类可暂空，不强行三选一。
+
+| 类别 | 判定条件 | 默认处置 |
+| --- | --- | --- |
+| **A · 明确遗漏** | 本期有效需求或验收条件明确；证据确认未实现、部分缺失或行为不满足；没有适用的已批准变更，且恢复原要求不需要新的产品取舍 | 纳入 follow-up，给出最小补齐范围和验收条件；无需重复询问是否修复已明确的要求 |
+| **B · 合理变更** | 有可核实的实现/可行性约束、替代方案及取舍依据；替代行为已实现并有相应证据；保持产品目标与验收承诺，或改变承诺已获有权决策者明确确认 | 保留变更及其依据，不要求机械恢复原实现；仍需同步文档或补验收的事项单列 follow-up |
+| **C · 需 Triage 的实现差异** | 实际与 PRD 不同，涉及范围、体验、权限/数据、外部契约、关键 NFR 或验收取舍，且现有决定不能确定处置；或约束导致原要求不能直接补齐 | 准备上下文与真实可行选项，请用户决定；未回答保持待决 |
+
+判定约束：
+
+- 「实现更方便」「工期不够」或开发者自述「合理」不能单独支持 B；可行性受限也不自动批准产品降级。无批准的承诺变更归 C。
+- 纯内部实现替换、用户可见语义和验收保持一致且证据充分，可归 B，不为技术细节额外求批。既有明确决定仍有效时直接沿用并引用，不重复 Triage。
+- 事实与处置分开：用户可决定接受限制、补齐或延期，不能用用户选择证明功能已实现。A 被明确豁免后保留原判定与决策轨迹；C 已决也保留原编号，不抹去曾经的差异。
+- 同一变更的适配部分与遗留缺口可以拆项并关联，不能用整项 B 吞掉未实现部分。明确遗漏如果修复将引入新的产品取舍，关联 C 先决策再定修复范围。
+
+## 4. 交互式 Triage
+
+有 C 时，先准备可审阅的报告和问题卡，再使用环境实际可用的 `AskUserQuestion`、`AskUserTool`、`request_user_input_async` 或等价交互工具；遵守工具当前模式/参数限制，不虚构工具调用。工具不可用时在聊天中提出同等清晰的问题并等待。用户明确要求不交互时，保存待决事项，不代替用户拍板。
+
+每张问题卡包含：
+
+1. **差异与来源**：G-ID、PRD 要求及定位、当前行为与代码/完成记录证据。
+2. **影响与原因**：受影响角色和场景、为何发生、已证实的约束及尚未知的事实。
+3. **待决定的具体问题**：例如是否接受现有限制，不能只问「这个怎么处理」。
+4. **可行选项和后果**：通常 2–3 项，如按 PRD 补齐、接受现状并修订需求、采用替代方案或延期；说明各自用户效果、范围、风险和验收变化。推荐项写理由，不凭空给工期或提供已知不可行方案；允许自由回答。
+
+- 交互问题本身带上问题卡的关键上下文，不能只写 G-ID 或让用户先翻报告才能理解选项；长证据用报告定位链接补充。
+- 按依赖顺序提问，一轮只问少量相互独立的问题；上游选择改变下游选项时先等上游答案。缺的是事实时请求材料或安排补证，不让用户凭偏好裁定代码事实。
+- 将明确回答写入决策账本：`D-ID → G-ID → 选择/理由 → 新验收边界 → follow-up/延期/豁免 → 用户确认日期与来源`。上下文中已给出的明确决定可直接登记；含糊回答只追问影响实施的部分。
+- 异步等待期间继续不依赖该决定的核查；默认选项、超时、空回答都不是批准。用户选「稍后决定」则保持待决，记录解除条件，不循环催问，也不把它改写成接受现状。
+- 收到决定后复核受影响需求、验收与关联差异，只重新打开因新证据或新决定失效的问题。
+
+## 5. 收敛 follow-up 并调用 dev-plan
+
+形成一份有来源的 follow-up 清单：未被明确豁免/延期的 A；C 决策要求的补齐或替代实现；B 或接受现状后必要的文档同步、验证补齐。证据缺口只有形成具体、已确定范围的调查/验证任务才纳入，不能包装成未经证实的修复需求。合并同根因任务，保留所有 G-ID/需求关联。
+
+- 已满足、无后续动作的 B、明确豁免或已延期到别期的事项不进入本次实施范围；报告保留理由、去向和重新评估条件。全部无 follow-up 时明确写「无需 gaps plan」，不创建空计划。
+- 清单非空时，**实际定位并读取可用的 `dev-plan/SKILL.md`，按其写计划流程、骨架和校验生成独立 gaps plan**；不止建议用户以后调用，也不在本技能复制一套开发计划模板。缺少该技能时查找可用安装位置；仍找不到则保留报告和交接清单，说明计划生成受阻，不能声称已创建。
+- 交给 `dev-plan` 的输入：PRD、原计划及相关记录路径，差异报告、代码基线，选定 G-ID 和 D-ID，已确定目标与验收、排除/延期项、相关代码证据和依赖。原 PRD 提供来源，用户确认的变更提供新目标，当前代码提供起点；不能让下游再次按旧 PRD 推翻已确认决定。
+- 使用 `<原计划名>-gaps` 作为默认代号，输出目录、重名处理和最终状态遵守 `dev-plan`。保留 PRD 需求 ID，并追踪 `需求 → G-ID/D-ID → gaps 任务/里程碑 → 验收`；只规划增量，不重做已完成里程碑，不复制旧计划的完成记录，初始化新计划未开始的进度。
+- 未决 C 不得作为已选方案进入计划。若仍在等回答，先保存报告；独立且已确定的 follow-up 可先成独立范围的计划，显式排除待决项。未决项影响该计划范围或关键依赖时按 `dev-plan` 标 `Blocked`，不能用假设绕过；不得把部分计划说成全部差异已处理。
+- 计划生成后回读，检查范围、决策、验收与报告一致，并在报告中回填实际路径、状态和 G-ID 去向。默认到计划交付为止，不开始执行 gaps plan。
+
+## 6. 完成检查与交付
+
+按报告合同保存并回读完整报告，检查：PRD 覆盖无静默漏行，A/B/C 有证据，待核实与待决未伪装成已解决，用户决定已落实到 follow-up，计划只含确认范围且链接真实。结束前核对输入/代码基线是否变化，只复核受影响结论。
+
+最终回复给报告链接、三类差异数量、待核实/待决数量，以及 gaps plan 的实际链接与状态（或无需生成/受阻原因）。报告落盘、用户决策、计划生成分别说明完成情况；有未决/缺证时不宣称整份 PRD 已完整交付。

package/skills/review-prd-dev-gaps/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PRD 开发差异核查"
+  short_description: "核对 PRD、完成计划与实际交付，分流遗漏、合理变更和用户决策，按需生成 gaps plan"
+  default_prompt: "使用 $review-prd-dev-gaps 核对指定 PRD 与已完成开发计划，追读里程碑记录并核实实际实现，保存三类差异报告；交互确认需 Triage 的差异，有 follow-up 时调用 dev-plan 创建 gaps plan。"

package/skills/review-prd-dev-gaps/references/report-contract.md

@@ -0,0 +1,72 @@
+# 差异报告与交接合同
+
+## 落盘
+
+- 默认将完整 Markdown 报告保存到用户指定路径；未指定时放在原开发计划旁，命名为 `<原计划名>.prd-dev-gaps.md`。仅有远程/聊天输入时，遵循仓库报告目录惯例，无惯例则用 `docs/reviews/<主题>.prd-dev-gaps.md`。
+- 按需建目录。已授权更新本报告时就地更新；否则同名文件存在则用日期后缀、再用递增序号，保留旧文件并告知实际路径。不得覆盖输入文档。
+- Triage 前先保存已有核查结果和待决问题；回答到达后在同一报告更新决策和去向，计划交付后补真实链接。恢复会话时先读报告、确认基线与已有决定，避免重复询问。
+- 用户明确仅聊天/不写文件时在聊天中交付完整内容，该限制同时传给 `dev-plan`。工具不能写入或写入失败时说明「未落盘」及原因，保留完整内容和未完成项，不链接不存在的文件。
+
+## 报告结构
+
+### 1. 结论与范围
+
+写明审查阶段、整体覆盖情况、A/B/C 数量、C 中已决/待决数量、证据不足数量、需跟进数量。无某类写 0；数量按独立 G-ID 统计，不能把需求数、差异数和任务数混算。
+
+整体结论可并列「存在明确遗漏」「存在合理变更」「待用户决策」「待补证」。只有范围内需求逐项核实且无缺口时，才能说在注明的基线和证据范围内已覆盖；报告完成与产品交付完成分开表述。
+
+### 2. 三类差异
+
+按 A 明确遗漏、B 合理变更、C 需 Triage 分组；组内按用户影响与依赖优先，无需机械打分。每项保留：
+
+```markdown
+#### G-01 · <具体差异> · <A/B/C>
+- PRD 期望：<需求/验收 ID，文件与章节/行定位>
+- 实际交付：<触发条件、可观察行为、与期望的差别>
+- 证据链：<计划里程碑 → 完成记录 → 代码/测试/运行证据；缺失环节明说>
+- 影响：<角色、场景、后果、是否阻塞主路径/验收>
+- 分类依据：<为什么是本类；B 附约束、备选取舍、目标等价或批准依据>
+- 处置：<补齐/保留/替代/延期/豁免/待决；关联 D-ID>
+- Follow-up：<最小增量及可观察验收，或无动作理由；后续计划任务定位>
+```
+
+只引用亲自读过的段落、代码符号和实际证据；短行定位或稳定标题可点击跳转。文档中互相冲突的主张同时列出处，不能选择方便的版本当真。去重不丢掉受影响的需求与场景。
+
+### 3. 完整需求覆盖账本
+
+| PRD 需求/验收及定位 | 本期范围/已批准变更 | 计划与里程碑 | 完成记录 | 实际行为与证据等级 | 覆盖状态 | G-ID/去向 |
+| --- | --- | --- | --- | --- | --- | --- |
+
+覆盖状态使用「已满足 / 部分满足 / 未满足 / 已确认变更 / 范围外 / 未核实」。这是实现覆盖，不是差异分类。无计划落点的需求也必须保留该行；不可访问的材料写明不可访问，不填「无」暗示不存在。
+
+一条 PRD 可能拆为多个可验收条件，多条 PRD 也可能共享同一根因差异；保留双向关联。跨期需求记录本期边界、后续去向与最终验收，不用局部完成代表整体交付。
+
+### 4. Triage 与决策账本
+
+待决区保存主技能要求的问题卡，含期望、实际、原因、影响、选项及后果。已决区记录：
+
+| 决策 ID | 关联 G-ID | 用户选择与理由 | 确认日期与来源 | 新目标/验收边界 | 跟进/延期/豁免去向 |
+| --- | --- | --- | --- | --- | --- |
+
+未回答或明确稍后决定时不生成「已确认」条目。已有历史决定注明来源；新回答摘要必须保持原意。改变已有决定时标注替代关系，不能默默覆盖。
+
+### 5. 待核实项与审查基线
+
+- 列出每项缺失事实/材料、影响的需求与结论、补证方式以及是否阻塞分类、决策或计划；未知负责人/日期不编造。
+- 记录 PRD/计划/记录版本、代码仓 commit/dirty、日期、环境、实际审查范围及验证方式。只列影响结论的来源，不堆读取日志。
+- 历史测试、当前静态检查、本次实测、线上验证分别标注；完成记录与当前实现不一致时解释基线差异，无法解释则待核实。
+
+### 6. Follow-up 与 gaps plan
+
+| G-ID / D-ID / PRD ID | 确定的增量工作 | 验收条件 | 依赖/阻塞 | gaps plan 任务或排除去向 |
+| --- | --- | --- | --- | --- |
+
+报告保留问题和决策的完整依据；计划承接最终目标、增量实施和验收，通过来源链接关联，避免复制整份报告。记录计划实际路径与 `Ready / Proposed / Blocked` 状态，或无需计划的理由；技能缺失、待用户决定、写入失败等分别标明受阻环节，不能以清单代替声称完成的计划。
+
+## 交付前核对
+
+- PRD 每个范围内的需求/验收均有覆盖行；原计划漏项仍能被发现。
+- 三类判定有依据，未知不算遗漏，未经确认的产品降级不算合理变更。
+- 每个 C 有待决问题或明确决策，每个待核实项有补证办法。
+- 每个应跟进项有计划去向或具体阻塞；豁免、延期与无需动作有理由。
+- 报告和计划均已回读，链接、状态、范围与决策一致；未决项未混入 Ready 计划的实施假设。

package/skills/rust/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: rust
+description: >
+  Guide for writing idiomatic Rust code, based on Apollo GraphQL's best practices handbook plus async patterns for Tokio. Use this skill when:
+  (1) writing new Rust code or functions,
+  (2) reviewing or refactoring existing Rust code,
+  (3) deciding between borrowing vs cloning or ownership patterns,
+  (4) implementing error handling with Result types,
+  (5) optimizing Rust code for performance,
+  (6) writing tests or documentation for Rust projects,
+  (7) writing async Rust with Tokio - tasks, channels, streams, async traits, graceful shutdown,
+  (8) debugging async code: deadlocks, blocked runtimes, cancellation, Send bounds.
+license: MIT
+compatibility: Rust 1.70+ (1.75+ for async fn in traits), Cargo
+allowed-tools: Bash(cargo:*) Bash(rustc:*) Bash(rustfmt:*) Bash(clippy:*) Read Write Edit Glob Grep
+---
+
+# Rust Best Practices
+
+Apply these guidelines when writing or reviewing Rust code. 
+
+## Best Practices Reference
+
+Before reviewing, familiarize yourself with the relevant chapters. Read ALL relevant chapters in the same turn in parallel. Reference these files when providing feedback:
+
+- [Chapter 1 - Coding Styles and Idioms](references/chapter_01.md): Borrowing vs cloning, Copy trait, Option/Result handling, iterators, import ordering, when to extract a function (duplication vs. wrong abstraction)
+- [Chapter 2 - Clippy and Linting](references/chapter_02.md): Clippy configuration, important lints, workspace lint setup
+- [Chapter 3 - Performance Mindset](references/chapter_03.md): Profiling, avoiding redundant clones, stack vs heap, zero-cost abstractions
+- [Chapter 4 - Error Handling](references/chapter_04.md): Result vs panic, thiserror vs anyhow, error hierarchies
+- [Chapter 5 - Automated Testing](references/chapter_05.md): Test naming, one assertion per test, snapshot testing
+- [Chapter 6 - Generics and Dispatch](references/chapter_06.md): Static vs dynamic dispatch, trait objects, dyn compatibility
+- [Chapter 7 - Type State Pattern](references/chapter_07.md): Compile-time state safety, when to use it
+- [Chapter 8 - Comments vs Documentation](references/chapter_08.md): When to comment, `SAFETY:`/`CONTEXT:` prefixes, TODOs as issues, doc comments, rustdoc
+- [Chapter 9 - Understanding Pointers](references/chapter_09.md): Thread safety, Send/Sync, pointer types
+- [Chapter 10 - Async Patterns with Tokio](references/chapter_10.md): Execution model, JoinSet, channels, streams, async traits, graceful shutdown, async debugging
+
+## Quick Reference
+
+### Borrowing & Ownership
+- Prefer `&T` over `.clone()` unless ownership transfer is required
+- Use `&str` over `String`, `&[T]` over `Vec<T>` in function parameters
+- Small `Copy` types (≤24 bytes) can be passed by value
+- Use `Cow<'_, T>` when ownership is ambiguous
+
+### Error Handling
+- Return `Result<T, E>` for fallible operations; avoid `panic!` in production
+- Never use `unwrap()`/`expect()` outside tests
+- Use `thiserror` for library errors, `anyhow` for binaries only
+- Prefer `?` operator over match chains for error propagation
+
+### Performance
+- Always benchmark with `--release` flag
+- Run `cargo clippy -- -D clippy::perf` for performance hints
+- Avoid cloning in loops; use `.iter()` instead of `.into_iter()` for Copy types
+- Prefer iterators over manual loops; avoid intermediate `.collect()` calls
+
+### Linting
+Run regularly: `cargo clippy --all-targets --all-features --locked -- -D warnings`
+
+Key lints to watch:
+- `redundant_clone` - unnecessary cloning
+- `large_enum_variant` - oversized variants (consider boxing)
+- `needless_collect` - premature collection
+
+Use `#[expect(clippy::lint)]` over `#[allow(...)]` with justification comment.
+
+### Testing
+- Name tests descriptively: `process_should_return_error_when_input_empty()`
+- One assertion per test when possible
+- Use doc tests (`///`) for public API examples
+- Consider `cargo insta` for snapshot testing generated output
+
+### Generics & Dispatch
+- Prefer generics (static dispatch) for performance-critical code
+- Use `dyn Trait` only when heterogeneous collections are needed
+- Box at API boundaries, not internally
+
+### Type State Pattern
+Encode valid states in the type system to catch invalid operations at compile time:
+```rust
+struct Connection<State> { /* ... */ _state: PhantomData<State> }
+struct Disconnected;
+struct Connected;
+
+impl Connection<Connected> {
+    fn send(&self, data: &[u8]) { /* only connected can send */ }
+}
+```
+
+### Async (Tokio)
+- Never block an async thread: no `std::thread::sleep`, blocking I/O or heavy CPU work in `async fn` - use `spawn_blocking`
+- Never hold a lock across `.await`; `std::sync::Mutex` is cheaper unless the guard must cross one
+- Bound concurrency with `buffer_unordered`/`Semaphore`; use `JoinSet` to own and abort task groups
+- Prefer channels over shared state - `mpsc` (work queue), `broadcast` (fan-out), `oneshot` (reply), `watch` (latest value)
+- Put a timeout on every outbound call; handle shutdown via `CancellationToken`
+- `async fn` in traits (1.75+) for static dispatch; `#[async_trait]` only when you need `dyn Trait`
+- Instrument with `tracing`: `#[instrument]` on async fns, `.instrument(span)` on spawned tasks
+
+### Documentation
+- `//` comments explain *why* (safety, workarounds, design rationale)
+- `///` doc comments explain *what* and *how* for public APIs
+- Every `TODO` needs a linked issue: `// TODO(#42): ...`
+- Enable `#![deny(missing_docs)]` for libraries