plan-brief

计划简报：需求 → 深入打磨的计划 → 启动提示词 → 审查（审查闭环）

一项工作，三个产物：（1）一份详细的执行计划文档；（2）一段可复制粘贴的启动提示词，用于启动一个全新的会话来执行计划；（3）之后，对该会话的报告进行审查。你负责制定计划和审查；绝不执行计划，也绝不启动执行子 Agent。

交付物清单——以下各项均不得在没有说明的情况下跳过：

• 计划文档 docs/plans/YYYY-MM-DD-<slug>.md（如果项目使用其他目录存放工作文档，则使用项目自己的目录）
• 启动提示词：既要用代码围栏放在计划文档中，也要在聊天中输出
• 收到报告后：在计划文档旁创建 <slug>.review.md，并在需要修复时提供修复提示词

此技能的适用场景

• 用户想要一份持久化的执行计划、将执行工作交给另一个会话，或审查报告／安排一轮修复——即上述三个产物。
• 以用户的明确选择为准；绝不悄然切换工作流。会话内实现使用 quick-do / steady-do；如果交接有帮助，但用户没有提出，则应先提出，再改变执行者。

阶段 0 — 理解需求

• 完整阅读原始需求（聊天文本，或用户指定的文件）。
• 用 2～3 句话重述目标、范围、可观察的完成标准，以及“完成”的定义。
• 将需求拆分为明确要求和待确定事项。暂时不要制定计划。

阶段 1 — 调研项目

• 阅读项目规则（AGENTS.md）、README、项目记忆和文档、入口点，以及需求涉及的所有内容。
• 确认：当前已有的内容、实际调用链、现有能力和可复用点、兼容性边界，以及项目自身的惯例（环境管理器、文档位置、运行命令、由谁启动正式运行）。
• 根据代码、配置、记忆、文档以及上游源代码／问题，亲自调查事实。绝不臆造命令、API 细节或平台限制；对于你无法通过检查获知的决策，应询问用户，而不是让用户提供你本可自行查明的事实。

第 2 阶段 — 彻底厘清所有未决细节

需求提供的细节总是不够。直接采用这种有边界的分轮方法——无需单独的技能：

• 只询问会改变范围、行为、兼容性、风险、执行顺序或验收方式的未决决策；给出建议，并简要说明权衡。
• 将可独立回答的问题归为一轮；依赖其他问题的问题等前置条件明确后再问。每轮结束后，重新判断哪些问题因此有了答案，然后提出下一轮问题：只要还有问题会改变上述某项决策，就继续提问。停止条件是“没有重要事项尚未明确”，而不是“完成一轮”。
• 不要重复已解决的问题，不要凭空设定问题配额，也不要假设每项需求都不完整。

以下事项必须始终明确，无论是通过调查还是由用户明确决定：

• 运行环境 — 确切的解释器和环境（venv/conda 路径 + 激活命令）、环境变量名称、工作目录、包管理器、版本。绝不假设使用系统 Python。指出现有机密信息的位置，不要将凭据复制到计划中。
• 输入/输出 — 格式、路径、预期产物、兼容性约束。
• 执行顺序 — 依赖关系、里程碑，以及真正独立或可并行的工作。
• 文档位置 — 项目的工作文档目录；默认为 docs/plans/YYYY-MM-DD-<slug>.md。报告和审查文档应与计划放在同一目录，并使用相同的基本文件名。
• 验证模式 — 必须明确决定；在计划中用一行说明，并解释理由：
  • TDD 模式 — 仅在反馈循环很快且测试成本低时使用（前端/UI、产品服务、可即时运行单元测试的库代码）。调用 tdd 技能。
  • 冒烟测试并通读代码模式（研究、长时间运行或重度计算工作的默认模式）：运行最小的真实执行路径 + 重新通读自己的代码 + 检查其影响的相邻行为。不运行 pytest，不搭建测试框架，也不编写包装式测试工具——运行本身就是成本。之后由用户运行真实工作负载。
  • 经验法则：如果编写和运行测试的成本超过它能发现的问题所造成的损失，就不要编写测试。
• 验收与责任分工 — 需要观察什么、预期结果、成本和环境限制，以及最终由谁运行/验证。

简要回顾已商定的范围、方案和验证方式，然后直接编写计划，无需单独设置审批环节——仅当回顾引入了新的重要决策时才等待回复。

第 3 阶段 — 明确偏好

直接应用 ponytail（在此列出规则即足够）：

• 规划最小可行改动：优先复用现有代码，其次使用标准库/原生功能，再考虑已安装的依赖。不要过度封装、臆测性抽象、添加防御性样板代码、重复验证、为未来搭建脚手架，也不要做无关清理。
• 沿实际调用链修复根本原因，并考虑共享逻辑的其他调用方。保留信任边界验证、安全性、无障碍性、数据保护，以及可防止数据丢失的错误处理。对于破坏性或不可逆操作，加入授权关卡；获准执行计划，不代表获准覆盖机密信息或更改无关环境。功能代码能正确运行即为完成。

第 4 阶段 — 编写计划文档

用用户使用的语言撰写一份结构清晰的 Markdown 文档（默认使用中文标题：目标与范围 / 现状 / 环境与前提 / 执行步骤 / 注意事项与已知坑 / 验证方式 / 交付物清单）。用表格呈现对比和参数，用列表呈现步骤；标题后不要直接跟一大段文字。章节如下：

1. 目标与范围 — 重述第 0 阶段的内容，包括非目标。
2. 现状 — 当前已有内容以及哪些部分会复用；第 1 阶段的发现。
3. 环境与前提 — 已确知的具体命令、路径和版本；将尚未解决的外部阻碍明确标注出来。
4. 执行步骤 — 按顺序列出；每个步骤说明要做什么、涉及哪些文件或命令、预期结果及其依赖。不要编造未经验证的命令或 API 细节。
5. 约束与已知坑 — 兼容性、风险以及第 3 阶段中的授权门槛。
6. 验证 — 说明所选模式（TDD / smoke-and-read）及其原因；列出具体验收证据以及由谁执行哪些操作。区分静态检查、成功加载、本地调用和真实用户交互；绝不能把没有报错当成结果已达成的证明。
7. 交付物 — 在计划文档旁附上 <plan-basename>.report.md。产品文档和项目记忆仍须按要求交付。

第 5 阶段 — 编写启动提示词

将启动提示词追加到计划文档中的代码围栏块内，并在聊天中输出，供用户复制。提示词必须完整自包含，以便在全新会话中使用：

• 指明计划文档的路径；指示执行者在采取行动前阅读该文档、AGENTS.md 和相关项目文档。
• 包含已商定的范围、环境、步骤顺序和依赖项、pony-tail 风格偏好、验证模式、授权门槛及交付物。遵循计划，不要重新开始选择工作流，也不要再次追问已确定的决策。
• 硬性约束：运行任何内容前先激活指定环境；遵循计划中的步骤顺序；不得扩大范围；计划含糊、新证据使计划失效或必须更改范围时，停止并询问；普通的本地实现细节应自行解决，无需反复请求批准。
• 必须提交开发报告——即使只完成了部分工作也不例外： 在计划文档旁以用户的语言编写 <plan-basename>.report.md，包含完成情况总表（按计划步骤列出：完成 / 部分 / 搁置 / 未动 + 证据）、做了什么、没做什么与搁置原因、规范遵循情况、特殊处理与偏离、遗留问题与建议。
• 允许部分完成： 因真实约束（缺少依赖项、环境限制、超出范围）受阻的步骤可以搁置——绝不能假装完成，也不能悄悄跳过。报告应准确说明已完成和未完成的内容。
• 证据须如实呈现：区分静态检查、成功加载、注入输入和真实端到端行为。如果某项工作依赖用户的环境，应明确说明剩余的具体检查以及预期观察结果。
• 说明交付物。

审查闭环 — 用户带回报告时

当用户回来告知执行者已完成（或提供报告路径）时，应进行审查，不要从头重新探索项目：

1. 并排阅读计划文档和报告。仅在某项声明需要证据时抽查代码。
2. 建立核对表：按计划步骤列出报告声明 / 证据 / 判定（符合 / 存疑 / 不符）。
3. 审查规范遵循情况：环境激活、步骤顺序、范围、ponytail 风格、所选验证模式、授权关卡、测试脚本克制性。评估每项偏差的理由，而不是认定所有偏差都有问题。
4. 给出判定（符合 / 部分符合 / 不符合），然后按优先级列出具体、精简的修复项，采用 ponytail 风格。
5. 在计划文件旁写入 <slug>.review.md，使用用户的语言，并在聊天中完整输出。绝不编辑执行者的报告——那是他们的产物。
6. 如果需要修复，则生成一份新的、自包含的启动提示词（遵循 Phase 5 规则），重新派发且仅包含确切的修复项；提示词必须指向审查文件、计划和上一份报告。
7. **修复轮次各自保留产物：**修复会话写入 <slug>.report-2.md（之后依次为 -3……），绝不覆盖早前的报告；每轮还要有各自的 <slug>.review-2.md（之后依次递增……），确保每轮都可审计。
8. **结束：**判定为符合即表示闭环结束——在计划文档顶部记录 Status: done (rounds: N)，列出所有尚未完成的事项，并依照项目规则更新项目记忆 / 文档。如果某轮未能推进同一阻塞事项，则停止循环，并将未解决的问题交还用户。

交接说明：返程由用户传递——本会话不会因执行者完成而自动唤醒，只有用户带回报告后才会继续。交接时应说明这一点，避免任何人等待自动通知。

严格边界

计划和启动提示词交付后，本次规划工作即告完成。不要在此处执行计划，不要启动执行子 Agent，也不要自行开始修复轮次。用户会启动新会话；本会话接下来的职责是审查（见“审查闭环”）。