plan-auditor

计划审查员

使用此技能审查现有的 PlanWeave 计划。默认输出为问题发现和修订顺序；审查期间不要导入新计划、执行区块、修复状态或重写软件包。

快速开始

1. 找出权威依据：用户请求、PRD、架构、设计文档、当前代码和 PlanWeave 软件包。
2. 在存在时读取 project-graph.json、每个画布的 manifest.json、源提示词、任务／区块定义、画布结构、依赖项、验证输出，以及 planweave schema 输出。
3. 在判断任务是否完整之前，先识别计划的主要价值流或生命周期流，并填写必需的流程覆盖表。
4. 将计划与实际目标、数据流覆盖、对象生命周期、契约、执行顺序、提示词、失败路径和验证标准进行比较。
5. 首先报告结论：PASS、NEEDS_REVISION 或 BLOCKED。
6. 按严重性列出问题发现，并提供证据和具体的计划变更。

计划更新边界

• 审查发现应指出需要更新的任务、区块、边、提示词、评审或验证；不得直接应用变更。
• 如果用户明确要求应用修订，先完成审查，然后使用 Plan Package 的语义编辑边界：解析 CLI 工作区路径，仅编辑修订所需的 project-graph.json、画布 manifest.json 和源提示词 Markdown，并运行画布范围和项目级验证。
• 使用此技能时，不要编辑运行时 state.json、results/、活动画布选择、恢复事务或实现产物。

必需输出

1. 结论：PASS、NEEDS_REVISION 或 BLOCKED。
2. 在问题发现之前提供流程覆盖表。
3. 按严重性列出问题发现。
4. 建议的修订顺序。

流程覆盖表：

流程	触发条件／输入	核心处理	外部依赖	状态／存储	接口／使用方	输出／副作用	失败路径	验证	缺口

对于每个单元格，只要存在，就引用精确的 PlanWeave 任务／区块 ID、提示词、参考文件和验证方法。对于缺少任务覆盖、提示词覆盖、依赖边、验证、实际行为或必要失败处理的情况，使用 Gap: 标记。

审查清单

目标覆盖

• 在判断计划之前，确定权威目标。
• 检查是否体现了所有关键目标、要求、约束和风险。
• 标出被遗漏、弱化或错误延期的要求。
• 除非用户明确将交付范围限定为演示子集，否则不要将演示子集视为完整交付。

数据流覆盖

• 此部分为必需内容，必须在判断任务列表是否完整之前完成。
• 识别计划的主要价值流或生命周期流。流程是指任何输入、决策、对象、用户操作、外部事件或定时作业在系统中流转并产生可观察结果的路径。
• 对每个主要流程，追踪适用阶段：来源／触发条件／输入；验证／规范化／解析；规划／决策／编排；处理／转换／执行；外部依赖／提供方／模型／工具调用；状态／持久化／缓存／产物存储；契约／接口／API／CLI／事件／消息；用户或下游使用；输出／副作用／产物／报告；错误／重试／取消／恢复；验证／可观测性／验收证据。
• 将每个适用阶段对应到精确的 PlanWeave 任务／区块 ID、提示词、参考文件、依赖边和验证方法。
• 如果某个必需阶段没有任务、提示词、依赖边或验证，或者目标要求实际行为但计划只覆盖了模拟行为，请报告缺口。
• 不要因为任务列表很长，就在端到端流程不完整时仍视为覆盖充分。

核心对象生命周期

• 在检查 UI/API/数据库/工作线程任务之前，先识别项目的核心对象。
• 对每个对象，追踪由谁创建、由哪种结构描述、在哪里验证、由谁转换、状态如何变化、是否会存储、由谁使用、会触发哪些副作用、最终输出是什么，以及如何处理失败／重试／回滚／人工干预。
• 如果某个对象有生产者却没有消费者，或有设置却没有最终输出，请记录这一缺口。

契约一致性

• 检查架构、类型、API 参数、CLI 标志、事件、文件格式以及提示词输入／输出。
• 生产者和消费者必须使用相同的字段、状态和语义。
• 涉及契约变更的任务，在相关情况下必须涵盖调用方、测试、测试固件、文档和迁移。
• 标记那些会掩盖契约缺失的回退、默认值、any 和仅用于 mock 的路径。

执行图

• 检查任务、区块、画布、项目图边和依赖边是否表达了真实的执行顺序。
• 并行任务在依赖可达性、数据流和契约时序方面必须相互独立。
• 将并行任务之间的共享资源重叠标记为非阻塞协调提示。如果重叠需要排序，则必须改为显式依赖。
• 不同画布并不天然并行；如果存在正式项目图，跨画布依赖必须在 project-graph.json 中显式声明。
• 画布级依赖必须使用项目图画布边；跨画布任务阻塞项必须通过 crossTaskEdges 显式声明。
• 将密集或重复的 crossTaskEdges、以任务边表达的阶段级排序，以及与画布顺序冗余的任务边视为画布边界缺陷。
• 要求紧密耦合的任务移至同一画布，并将阶段级依赖改为画布边。仅当跨任务边稀疏、不可约且有具体理由说明为何不应迁移任务或使用画布边时，才接受此类边。
• 标记仅在项目／全局提示词正文、README 文本或 Agent 指令中表达画布顺序的计划。
• 必须显式声明顺序门槛。
• 标记仅为凑数而拆分的任务，以及跨越过多边界的任务。
• 每个画布都应代表一个清晰的阶段、能力领域或并行工作组。

任务与评审粒度

• 合理的任务应对应一个可验证的功能切片、契约切片或生命周期阶段。
• 合并那些只会增加调度开销的微小任务。
• 拆分那些会迫使子 Agent 跨越无关层级，或无法掌控验证过程的任务。
• 简单的文档、配置、低风险文案编辑和局部修复通常不需要评审。
• 跨层、契约、数据库、提供方、架构、安全、隐私或高风险行为变更应设置评审门槛。

提示词质量

• 每个任务／区块提示词都应让子 Agent 无需猜测即可开始工作。
• 检查提示词是否包含目标、参考文件路径、影响范围、禁止操作、完成标准和验证方法。
• 如果计划依赖全局／项目提示词，请确认这些提示词包含所需背景信息。
• 检查提示词位置摘要是否指出全局／项目／任务／区块层面的事实来源。
• 标记那些只说“实现这个”却不说明如何判断是否完成的提示词。

真正完成

• 查找虚假完成的情况：架构已定义却未在运行时使用、接口没有调用方、UI 没有行为、配置从未读取、提供方抽象没有实际客户端、队列没有消费者、文件路径对应的文件不存在、只有 dry-run 而没有实际路径，或测试仅使用测试固件却未覆盖真实链路。
• 检查复杂区块是否包含架构边界、测试位置、配置／环境变量处理，以及适用时对 README 或 .env.example 的更新，并明确真实提供方与 mock 的预期。
• 要求计划区分 mock、dry-run、实际运行路径和真实产物。

失败路径

• 检查错误、重试、取消、超时、权限、部分成功、外部服务中断、人工审核失败和恢复。
• 可靠执行和状态机工作必须尽早纳入异常状态和恢复策略，而不是将其作为最后的润色任务。

验证标准

• 每个区块都需要可验证的完成标准。
• 优先采用具体命令、测试、输出产物、可观察的状态变化或端到端流程。
• 拒绝“逻辑正确”“已实现”或“看起来可用”等含糊标准。

架构质量

• 检查层边界、唯一事实来源、重复定义架构或规则的风险、临时回退方案、将模拟实现当作产品的风险、可测试性和可维护性。
• 除非明确要求，否则标记从无关项目复制的技能、引导规则或提示词约定。
• 如果基础任务尚未完成，标记过早安排大型 UI 或打包层的计划。

PlanWeave 可执行性

• 检查 PlanWeave 是否真的能运行该计划：提示词是否存在、区块能否被认领、依赖是否能解锁、是否可以提交审核、提示词来源是否可编辑，以及画布顺序是否清晰。
• 对于正式的多画布计划，验证 project-graph.json 是否存在、每个画布是否指向现有包、每个跨任务引用是否都解析到真实任务，以及画布依赖和跨任务依赖中是否不存在循环。
• 确认单画布的 manifest.json 语义仅限于该画布；跨画布依赖的强制执行不得隐藏在本地清单或提示词正文中。
• 将可疑的项目图、清单、状态和布局结构与 planweave schema project、planweave schema manifest、planweave schema state 和 planweave schema layout 进行比对。
• 区分计划设计缺陷和 PlanWeave 工具链缺陷。

发现格式

每条发现都采用以下格式：

[P1] Short title
Evidence: path/ref/line or task/block/canvas id.
Impact: why this blocks or weakens execution.
Plan change: exact task, block, edge, prompt, review, or validation update needed.

最后给出建议的修订顺序。不要止步于泛泛的建议。