snuffish/plan

技能：/plan — 实施计划管理器

管理当前会话的活动实施计划（<前缀>-implementation_plan-<后缀>.md）。该技能拥有计划的骨架、状态值、链接块和审查（--review）。每个其他写入或读取计划的命令（/implement-feature、/problem、/refine、/pr-fix-pipeline、/proceed）都使用此处定义的设置。

---

模块

路径相对于该技能的实际文件夹。首先对该技能的基本目录执行 realpath 操作（它可能是一个符号链接），然后从该路径解析每个模块路径。如果无法读取任何模块，请停止并报告该路径。如果缺少模块，请勿继续。

在步骤 1 之前读取以下文件：

• ../_modules/core.md
• ../_modules/artifact-protocol.md：在工件目录（artifact-protocol）中写入 <前缀>-implementation_plan-<后缀>.md
• ../_modules/project-profile.md：仅基础配置文件（无命令配置文件），用于审查（情况 D）；读取每层引用、合同接触点、兄弟链以及可选的“计划审查检查”字段

按需引用（references/）：

• references/review.md — 五个审查支柱（情况 D 步骤 3）以及 --review（情况 D）和自审（情况 B 步骤 4）的报告模板

---

1. 计划合同

状态值

计划的第二行包含 **状态：** <值>，其中一个值为：

值	含义	由谁设置
Draft（草稿）	正在编写中；尚未准备好审查	编写者，在草稿阶段
Awaiting User Review（等待用户审查）	已完成并等待在门口	编写者，在呈现时
Approved（已批准）	用户打开了门；实施正在进行中	core › /proceed 门
Completed（已完成）	范围内的所有阶段已完成并验证	core › /proceed 门

值后面可以跟一个简短说明（Approved — phase 2 of 3 done）。读取器仅匹配前导值。

骨架

<!-- artifact-owner: … -->                 <!-- artifact-protocol › Claim -->

# 实施计划：<标题>

**状态：** Awaiting User Review
**后缀：** `<后缀>`
**输入：** <调查 / 审查 / 工单链接，或 "none">
**审查：** <_情况 D_ 折叠后的结论> · <n> 个发现 <!-- Case B step 4 -->

## 1. 背景与目标

## 2. 决策 <!-- 表格：决策 · 原因 -->

## 3. 建议的更改 <!-- 按阶段或仓库：[NEW|MODIFY|DELETE] <路径> — 内容及原因 -->

## 4. 验证计划 <!-- 精确命令，加上手动步骤 -->

## 5. 风险 <!-- 表格：风险 · 缓解措施 -->

## 6. 任务清单 <!-- 实时清单：[ ] / [/] / [x] -->

## 7. 未解决的问题 <!-- 未解决的问题；始终放在最后，如果有的话；每个都有建议 -->

命令可以添加它需要的部分（/implement-feature 添加了 User Review Required、Blind-spot Pass 和 Cross-repo order）。它保留这七个部分，按此顺序，以便 /plan、/plan --review 和 /proceed 能找到它们。Open Questions（未解决的问题）始终是最后一个部分；添加的部分放在它之前。

风格

用户的规则（~/.claude/CLAUDE.md › Plan Mode）适用：极其简洁，牺牲语法；以 Steps 结尾，然后是 Unresolved questions（每个都带有建议，如果没有则省略）。

每个计划编写者将其应用于整个文件以及呈现计划的聊天回复：

• 片段，而非散文：没有段落，没有完整句子解释。
• 每个要点一个想法；将较长的要点拆分为子要点。
• Decisions 和 Risks 使用表格。
• 每个未解决的问题都带有 Rec:，给出推荐的答案。
• Open Questions 之后没有内容。如果没有未解决的问题，则注明“None”（或省略）。

链接块

每个呈现计划的聊天回复都以 artifact-protocol › Chat link block 开头（使用写入文件后 grep -n '^#\{1,3\} ' <file> 的实际行号），链接到 Context & Goal、Proposed Changes、Verification Plan 和 Open Questions，后跟 **状态：** <值>。命令可以在每个部分链接后附加一行摘要（/plan --review 会这样做）。

---

2. 核心行为

从参数中选择情况，第一个匹配获胜：

参数	情况
包含 --review	D：审查计划
以 preview 开头	C：预览
无	A：裸露
其他任何内容	B：起草或更新

情况 A：裸命令（/plan 无参数或消息）

1. 定位计划： 在工件目录（artifact-protocol）中扫描 <前缀>-implementation_plan-*.md，并根据 artifact-protocol › Claim › Readers & family selection 选择文件族（告诉用户下次可以使用 /plan <后缀> 跳过提示）。如果不存在，则说明情况，并提议根据用户的下一个提示创建一个。
2. 呈现链接块（§1 链接块）给所选计划，包含其当前 Status。不要编辑任何内容或运行后台命令。

情况 B：带指令的命令（/plan <指令>）

1. 解析上下文相关后缀，根据 artifact-protocol › 规则 2。
2. 规划，但不更改代码：
   • 首先检查是否已存在调查报告。 如果工件目录（artifact-protocol）中存在 <前缀>-investigation-<后缀>.md 并且涵盖此主题，则在其上构建：其 Plan Seed、Options & Trade-offs 和 Confidence Ledger。不要重新运行它已记录的研究；但请解决计划所依赖的任何 ❓ Unknown。
   • 否则，以只读方式研究相关代码。如果主题很大或未知项很多，请先运行 /investigate。
   • 根据项目自己的约定进行设计：其工作区规则书、项目范围的引用和配置文件（core › Precedence）。
3. 编写计划，使用 §1 骨架，在工件目录（artifact-protocol）中：
   • 新计划： 在会话私有路径中起草，然后通过 Claim（artifact-protocol › 规则 4）发布。如果基本名称已被占用，Claim 会写入 …-2.md；使用其打印的路径并在聊天中说明。
   • 现有计划： 仅当拥有者标记命名此会话，或者用户指定了该文件并要求更新时（artifact-protocol › 规则 3），才更新它。否则，通过 Claim 编写一个新版本，并在 Inputs 中链接它取代的那个版本。
   • 完成时将 Status 设置为 Awaiting User Review。在 Antigravity 下，当在 <appDataDir>/brain/<conversation-id>/ 内写入镜像工件副本时，在 ArtifactMetadata 中设置 UserFacing = true 和 RequestFeedback = true（在工件目录文件上省略 ArtifactMetadata）。
4. 呈现前进行自审： 读取 references/review.md 并在主上下文中对刚刚编写的计划运行 情况 D 步骤 2–3。使用其支柱和严重级别。不要打印其报告或其门：这是草稿的一部分，用户审查的是折叠后的计划。

   • 在呈现前将每个发现折叠到计划中：

     发现	放入
     🔴 / 🟡，已验证（path:line 重新打开）	Proposed Changes、Task Checklist 以及一个没有修复就会失败的 Verification Plan 检查
     🔴 / 🟡 需要用户决定	Open Questions，带有 Rec:
     🟢	如果是一行则应用；否则丢弃
     被拒绝的发现	Risks，一行列出原因

   • 重新阅读一次计划，检查是否有任何修复矛盾的内容（先前的步骤、测试、决策行），并修复它。

   • 只运行一次审查。在 Review: 标题行中填写折叠计划将获得的结论。

   • 对每个新计划以及每个更改了 Proposed Changes 或 Verification Plan 的更新运行它。对于仅勾选清单或更改 Status 的更新，跳过它。

5. 呈现计划： 链接块（§1 链接块）、审查结论以及改变设计的发现（每个一个要点）、作为片段要点的关键决策，最后是未解决的问题，每个都带有其 Rec:（§1 风格 也适用于此聊天文本：无段落，无完整句子）。等待用户打开执行门（core › /proceed 门）后再进行任何代码更改。

情况 C：预览命令（/plan preview [目标]）

在宿主的规划预览面板中显示现有计划（可用时使用 ExitPlanMode），以便用户可以交互式地阅读、评论和批准它。

1. 解析计划： 使用参数（路径或后缀）、会话的活动计划文件或工件目录中的最新计划族（情况 A）。
2. 宿主能力检查： 如果宿主缺少 ExitPlanMode（例如 Antigravity IDE），则输出计划的链接块（情况 A）并解释宿主直接通过 Markdown 链接呈现计划。
3. 进入计划模式并复制： 调用 EnterPlanMode，从系统消息中读取宿主计划文件路径，并将源计划复制到其中（省略前导的 <!-- artifact-owner: … --> 注释）。
4. 打开预览： 调用 ExitPlanMode。
5. 处理决策：
   • 批准：用户授权实施（core › /proceed 门）。开始执行。
   • 继续规划 / 反馈：保持在计划模式，将反馈传递给情况 B 以更新计划，并重新打开预览。
   • 关闭 / 错误：报告状态并提供文件链接。

情况 D：审查命令（/plan --review [目标]）

严格、只读的实施计划、架构建议或变更设计审计，在编写任何代码之前。直到 /proceed（core › /proceed 门）之前都是只读的：

• 即使计划完美无瑕，也绝不编辑文件、运行修改命令（迁移、提交、搭建框架）或开始实施。
• 在 --review 下的每个响应，包括后续跟进，都以链接块开头：用户通常会关闭计划选项卡并从聊天中重新打开它。

使用错误工具：

情况	改用
代码差异、分支或 PR，而不是计划	/code-review
PR 上的审阅者评论和投票	/pr-feedback-review
计划存在之前的研究	/investigate
设计的隐藏假设和失败模式	/what-am-I-missing

读取 references/review.md 并执行 情况 D 步骤 1–4（步骤 1：定位计划；步骤 2：读取项目规则；情况 D 步骤 3：根据五个支柱 + 项目配置文件的 Plan-review checks 进行评估；步骤 4：呈现链接块和审查报告），然后等待在 core › /proceed 门。