--- name: grounded-critique description: "知识驱动的批判性审查。基于 DeepWiki 知识和 ToT 多视角推理，对设计、代码或方案进行结构化审查。" --- # 知识驱动的批判性审查 本技能用于 **grounded_workflows** 工作流中的 **质量门禁与风险收敛阶段**：在用户请求对设计文档、实现代码、技术方案或变更草案进行评审时，智能体必须将结论 **锚定** 于项目内 **`.deepwiki/` 知识（`[DW]`）** 与必要时补充的 **源码真值（`[SRC]`）**，并通过 **Tree of Thoughts（ToT）多视角推理** 组织审查路径，最终输出 **可追溯、可执行、可归档** 的审查报告。 **核心目的**：不是「泛泛挑刺」，而是在证据链约束下 **系统性暴露缺陷与不一致**，区分 **必须阻断的问题**、**应纳入债务跟踪的风险** 与 **可择机采纳的优化**，并保证读者能复核每一条重要判断的依据层级。 --- 审查意见必须基于 [DW] 知识。无知识支撑的批评必须显式标注 [EXT]，并说明为何 [DW] 和 [SRC] 不足。 禁止在有 [DW] 可用信息时绕过它直接给出 [EXT] 意见。 --- ## 协议引用 执行本技能时，智能体必须显式依赖下列协议文件（路径相对于 `grounded_workflows` 仓库根目录；若本仓库以符号链接安装于 `~/.cursor/skills/`，仍应能在工作区或用户指定的项目根找到对应 `protocols/` 副本，或从安装路径读取等效文件）： | 协议文件 | 使用时机与要求 | |----------|----------------| | `protocols/context-building.md` | **步骤 2**：在知识就绪后 **完整读取并严格执行**；按五步流程从 `.deepwiki/` 构建与审查目标 **强相关** 的结构化上下文，禁止跳过大纲匹配、禁止无差别通读全部页面。 | | `protocols/grounding.md` | **贯穿全程**：每一条审查结论、严重程度判定、修复建议与因果解释，均须遵守 `[DW]` / `[SRC]` / `[EXT]` 优先级、混合标签规则与扩展门控；`[EXT]` 不得与已检索到的 `[DW]` 事实断言相矛盾。 | | `protocols/tot-reasoning.md` | **步骤 4**：将「多视角审查」落实为 ToT 的可审计流程；在 **生成（视角）→ 展开（发现）→ 评估（严重度与证据强度）→ 筛选（纳入报告的发现集合）** 上与该协议对齐，并强制与 grounding 的标签及引用格式一致。 | --- ## Checklist 智能体必须 **按顺序** 完成下列 5 步；不得在步骤 2 未完成时直接输出最终报告；不得在审查对象未澄清时假装已理解范围。 1. **知识就绪检查** - 使用 Shell（例如 `test -d .deepwiki && ls .deepwiki`）在工作区 **项目根** 下检查 `.deepwiki/` 是否具备 `context-building` 所依赖的最低结构（通常包含 `README.md`、`_outline.md` 与 `pages/`）。 - **若未就绪或明显残缺**：不得将空目录或占位 wiki 当作依据；应向用户说明缺口，并 **引导其先调用 `grounded-knowledge-prepare` skill**（或等价流程）生成/修复知识库后 **重新开始本技能**。 - **若已就绪**：进入步骤 2。 2. **加载知识** - 读取并严格执行 `protocols/context-building.md`。 - 从 `.deepwiki/` 按审查主题关键词匹配大纲并 **选择性加载** 相关 `pages/*.md`，产出带 `[DW]` 前缀与 **可定位路径** 的结构化上下文块；作为后续发现的 **首选事实源**。 - 若审查目标包含 **具体实现核对**（例如函数行为、配置默认值、调用链），在 `[DW]` 覆盖不足或疑似过时时，按 `grounding.md` 使用 **Read / Grep / SemanticSearch** 补充 `[SRC]`，并在条目中用混合标签（如 `[DW+SRC]`、`[SRC+DW]`）如实反映主从关系。 3. **确定审查对象** - 明确 **被审物** 的类型与边界：设计文档（路径/章节）、Pull Request / 分支差异、独立技术方案、计划片段、接口契约草案、配置变更等。 - 若用户描述含糊（未给出仓库相对路径、未指定 commit/PR、未说明期望的审查深度），**必须先澄清再进入 ToT**：一次只问一个关键问题，优先给出可选项（含「其他，请说明」）。 - 将澄清结果固化为 **审查范围陈述**（写入报告 §1 或等价位置），避免后续发现越界或遗漏核心交付物。 4. **ToT 多视角审查** - 读取 `protocols/tot-reasoning.md`，将「视角」视为 ToT 的 **方向（Direction）**：须 **不少于 3 个** 在认知上可区分的审查视角（示例：**架构一致性**、**性能与容量**、**安全性与合规**、**可维护性与演进成本**、**兼容性与迁移风险**、**可观测性与运维**；按审查对象裁剪，但数量底线不变）。 - **展开**：对每个视角列出 **具体发现（finding）**；每条发现须可独立验证，并带 `[DW]` / `[SRC]` / `[EXT]`（或允许的混合标签）与 **可定位引用**（wiki 页、源码路径与行号范围）；`[EXT]` 必须附 **L1/L2 不足** 的一句话说明。 - **评估**：为每条发现标注 **严重程度**：`Critical` / `Warning` / `Suggestion`（定义见下节「严重程度定义」），并简要说明 **若不予处理的最坏后果** 与 **证据强度**（是否多源交叉验证）。 - **筛选与排序**：合并重复表述；剔除与审查范围无关项；对保留项按 **Critical → Warning → Suggestion** 与 **业务/发布阻断优先级** 排序，确保报告 **可先执行最高优先级行动项**。 - 在本步完成前，**禁止** 仅输出笼统结论而不列出视角、发现与严重度。 5. **输出审查报告** - 使用 `templates/critique-output.md` 作为 **唯一结构骨架**：完整填充各章节（含日期、审查目标、知识来源路径、来源统计、`[DW]`/`[SRC]`/`[EXT]` 计数）。 - **§1 知识上下文** 必须与步骤 2 实际加载内容一致；**§2 审查视角** 映射步骤 4 的 ToT 视角与要点；**§3 发现** 按严重度分栏列出，禁止空壳小节（无问题时写「无」并简述检索范围）；**§4 总结** 给出可跟踪表格与 **一句话结论**（例如：是否可合并、需修订后再审、仅建议优化）。 - 若用户需要落盘，使用 **Write** 将报告写入约定路径（如 `docs/reviews/`）；若仅在会话中交付，仍须 **一次性输出完整 Markdown**，不得省略模板章节标题。 - 交付后可建议：若发现大量 `[DW]` 与 `[SRC]` 冲突，优先 **更新 wiki 或修正实现** 后再走 `grounded-planning` 或二次 `grounded-critique`。 --- ## 严重程度定义 审查中每条 **发现（finding）** 必须映射到下列三类之一；若介于两类之间，**就高不就低**，并在条目中解释理由。 - **Critical（阻塞级）**：阻碍版本发布、合并或关键路径推进；或 **已证实** 将导致运行时故障、数据损坏、权限突破、严重违背项目在 `[DW]` 中声明的 **核心架构红线/安全基线**；或缺失该修复则后续工作建立在错误前提上。**默认需要立即处理或明确否决当前变更。** - **Warning（警告级）**：在证据链下成立的 **潜在缺陷**、可累积的 **技术债务**、与项目既有模式/接口契约 **不一致** 的实现、性能或可用性在特定负载下可能恶化的设计；不一定会立刻故障，但 **应在排期内修复或显式接受风险**。 - **Suggestion（建议级）**：在不影响正确性与安全前提下的 **体验、可读性、测试覆盖、日志粒度、命名与注释** 等改进；或依赖较弱的 **优化方向**（nice-to-have）；实施与否由团队权衡。 > 严重度与标签正交：**同一严重度** 的发现仍须分别标注 `[DW]` / `[SRC]` / `[EXT]`，不得以严重度替代来源层级。 --- ## 流程图 ```mermaid graph TD Start[用户调用 critique] --> Check[知识就绪检查] Check -->|未就绪| KP[引导使用 grounded-knowledge-prepare] Check -->|就绪| Load[加载审查相关知识] Load --> Target[确定审查对象] Target --> ToT[ToT 多视角审查] ToT --> Report[输出审查报告] ``` --- ## 工具映射 | 步骤 | 工具 | 用途 | |------|------|------| | 知识就绪检查 | Shell（`test`、`ls`） | 判断项目根下 `.deepwiki/` 是否存在及 `README.md`、`_outline.md`、`pages/` 等结构是否满足 `context-building` 最低要求 | | 加载知识 | Read | 读取 `protocols/context-building.md`、`protocols/grounding.md`、`.deepwiki/README.md`、`_outline.md` 及按协议选中的 `pages/*.md` | | 源码核对（可选） | Read、Grep、SemanticSearch | 在审查代码或验证 `[DW]` 陈述时定位 `[SRC]` 证据（路径、符号、调用链、配置项） | | 确定审查对象 | 直接对话 | 单次澄清问题，收敛审查范围与交付物类型 | | ToT 多视角审查 | Read + 推理 | 读取 `protocols/tot-reasoning.md`，执行多视角生成、展开、严重度评估与筛选排序 | | 输出审查报告 | 直接输出 与/或 Write | 按 `templates/critique-output.md` 在对话中呈现完整 Markdown；需要归档时使用 Write 写入仓库内约定路径 | --- ## 与其他技能的关系 - **前置**：`grounded-knowledge-prepare` — 在 `.deepwiki/` 未建立或 **NOT_READY** 时，应先完成或接受风险后再审查。 - **上游协作**：常与 `grounded-brainstorming`、`grounded-planning` 产出的设计/计划文档衔接；审查时应 **回指** 这些产物的路径与版本。 - **横向约束**：凡涉及事实与引用，均以 `protocols/grounding.md` 为根规范；本技能 **HARD-GATE** 与 grounding 冲突时，以 **更严格** 者为准。 --- ## 常见反模式（禁止） - 未检查 `.deepwiki/` 或未按 `context-building` 加载知识即开始「凭经验」列问题清单。 - 将 ToT 退化为 **同义反复的三段话**（视角之间无实质差异维度）。 - 在有可检索 `[DW]` 的前提下，用 `[EXT]` 包装本可从 wiki 或源码证实的断言。 - 严重度全为 `Suggestion`，回避对架构冲突或安全风险的 **Critical** 标注。 - 报告中的来源统计、日期、页面路径与对话中实际引用的证据 **不一致** 或留虚假占位。 --- ## 成功标准（本技能可验收） - `.deepwiki/` 已检查；未就绪时正确引导 `grounded-knowledge-prepare`。 - 已按 `context-building` 加载与审查目标相关的 `[DW]` 上下文；涉及实现核对时已规范使用 `[SRC]`。 - 审查对象、范围与深度已在报告中 **显式陈述**；用户曾含糊时已通过澄清收敛。 - ToT：**≥3** 审查视角 → 每视角展开为具体发现 → 每条发现有严重度与来源标签 → 已筛选排序。 - 已按 `templates/critique-output.md` 输出完整审查报告，**来源统计** 与 **§3 发现** 条目一致。 - **HARD-GATE** 全程遵守：`[EXT]` 均附 L1/L2 不足说明；无「有 `[DW]` 却用 `[EXT]` 代替」的违规路径。