plannotator-setup-goal

设置目标

通过结构化探索、用户访谈和代码库探索，将一个想法转化为 goals/<slug>/ 下的目标包。

阶段

1. 重新表述

用你自己的话复述用户的需求。如果对话中已有丰富的上下文，就总结这些内容。如果目标过于简单或模糊，就对代码库进行少量浅层探索，以便形成切实的理解。控制在 2-3 句话内。继续之前，等待用户确认或纠正。

slug 明确后，创建目标目录：

mkdir -p goals/<slug>

工作用 JSON 文件和最终文档都放在 goals/<slug>/ 下。JSON 文件记录来源和迭代状态；Markdown 文件是面向用户、具有权威性的目标包。

**浏览器会话耐心规则：**Plannotator 的目标设置是由用户驱动的浏览器会话。启动访谈或事实收集命令后，务必保持耐心，持续等待用户提交、关闭会话，或明确要求你停止。不要仅仅因为界面处于空闲状态或用户需要时间，就关闭、终止、重启、刷新会话，也不要再打开一个副本。切勿通过关闭并重新打开会话来更新状态；如果前一个会话结束后需要重新运行，请先更新工作用 JSON 文件，再从该文件启动新命令。

**可选：先进行深度访谈（逐个提问）。**在构建精简访谈问题包之前，只要目标模糊或包含许多相互依赖的决策，就建议先进行一轮深度访谈；如果用户提出要求（“先深度访谈我”），则务必进行。此步骤是可选的：对于清晰、范围明确的目标，跳过深度访谈，直接构建问题包，这样深度访谈就不会与问题包“问题更少、杠杆效应更高”的理念相冲突。进行深度访谈时，逐字遵循以下流程，然后将已确定的决策纳入质量更高的访谈问题包（阶段 2）；如果深度访谈已充分明确范围，则直接纳入事实表（阶段 3）。

针对这个计划的每个方面，毫不留情地采访我，直到我们达成共识。沿着设计树的每个分支逐一深入，逐项理清各项决策之间的依赖关系。对于每个问题，都提供你推荐的答案。

一次只问一个问题。

如果某个问题可以通过探索代码库来回答，就去探索代码库，而不是提问。

2. 访谈问题集

构建一组精简的问题，以收集实现此目标所需的所有“事实”。将问题打包在一起，方便用户在 Plannotator 目标设置 UI 中快速作答。对于每个问题，请提供建议答案，并在选项能加快作答时提供选项。

不要提出显而易见的确认问题。如果答案可以从用户请求、对话或对代码库的简单探索中推断出来，就直接推断并继续。如果某个明显的方面存在重要细节，请将推断出的答案作为建议，并提供选项或自定义的“添加/更正此项”路径，而不是让用户重新陈述显而易见的内容。

通常需要关注的问题领域：

• 功能/变更是什么
• 面向哪些用户
• 要解决什么问题
• 行为会有哪些变化
• 成功的标准是什么
• 范围内和范围外的内容（最重要的事实确认领域）
• 需要考虑哪些边缘情况
• 适用哪些约束或先例

如果可以通过探索代码库来回答某个问题，就探索代码库，而不是提问。 只纳入确实需要用户判断的问题。优先选择数量较少、影响较大的问题，而不是面面俱到地询问显而易见的内容。

向用户展示前，先编写访谈问题集：

goals/<slug>/interview.json

{
  "stage": "interview",
  "title": "Short human-readable title",
  "goalSlug": "<slug>",
  "questions": [
    {
      "id": "scope",
      "prompt": "What should be in scope?",
      "description": "Optional clarification.",
      "answerMode": "multi-custom",
      "recommendedAnswer": "Your recommended answer.",
      "recommendedOptionIds": ["ui", "server"],
      "options": [
        { "id": "ui", "label": "UI" },
        { "id": "server", "label": "Server" }
      ],
      "required": true
    }
  ]
}

支持的 answerMode 值：text、single、multi、custom、single-custom、multi-custom。

将此命令作为受监控的前台进程运行，并耐心等待浏览器会话结束。用户阅读、编辑或提问时，命令可能看起来处于空闲状态；请让它继续运行：

plannotator setup-goal interview goals/<slug>/interview.json --json

该命令会在 stdout 上返回包含提交答案的 JSON。继续之前，将该结果原样写入 goals/<slug>/interview-result.json。一种便捷的写法是：

plannotator setup-goal interview goals/<slug>/interview.json --json | tee goals/<slug>/interview-result.json

如果用户在会话结束后修改答案，请更新 interview.json 并重新运行命令，而不是凭记忆重建整个问题集。如果用户关闭了会话，请停止并告知用户目标设置已关闭。

在继续收集事实之前，请仔细阅读每个答案和备注：

• 如果用户在答案或备注中提出问题、表达不确定、写了“不确定”“需要更多背景”或类似内容，请停止并在聊天中解决这些问题。在用户获得足够背景信息，或你重新运行修订后的访谈问题集之前，不要继续收集事实。
• 如果用户跳过了某个问题并附上备注，请将该备注视为有意提供的反馈，而不是空答案。在继续之前，请回应该备注、完善问题，或记录一项明确的假设。
• 如果用户跳过了某个问题且没有附备注，只有在缺失答案不会阻碍后续工作时才继续；否则，请在聊天中提出尽可能简短的跟进问题。

3. 事实清单

事实是对目标各项结果的简单描述。它应易于测试和验证。事实可以描述某个特定功能或系统方面的作用，也可以确定具体的 UI 和 UX。同样，事实就是任何可以通过自动化或手动测试进行测试和验证的内容。事实表述应简洁明了。从某种意义上说，事实清单是一份设计规范，但内容更精简，并且使用人类用户容易想象和理解的语言。

根据 goals/<slug>/interview-result.json 准备一份事实审核包。每条事实都应注明是否建议并预先选中自动化验证。

先写入事实审核包，再向用户展示。如果这是对先前事实审核的修订，请从 facts-review.json 和 facts-result.json 开始，包含先前已接受且 "accepted": true 的事实，并保留其状态。

goals/<slug>/facts-review.json

{
  "stage": "facts",
  "title": "Short human-readable title",
  "goalSlug": "<slug>",
  "facts": [
    {
      "id": "fact-1",
      "text": "The accepted fact text.",
      "accepted": false,
      "removed": false,
      "recommendedAutomatedVerification": true,
      "automatedVerification": true
    }
  ]
}

将此命令作为受监控的前台进程运行，并耐心等待浏览器会话结束。用户审核、编辑或提问时，命令可能看起来处于空闲状态；请保持运行：

plannotator setup-goal facts goals/<slug>/facts-review.json --json

命令会在 stdout 上返回 JSON，其中包含已接受、已编辑或已移除的事实，以及自动化验证选择。将该结果原样写入 goals/<slug>/facts-result.json。一种方便的写法是：

plannotator setup-goal facts goals/<slug>/facts-review.json --json | tee goals/<slug>/facts-result.json

将已接受的事实写入 goals/<slug>/facts.md，作为一份扁平、易读的列表。每条事实占一行；仅当事实本身无法清楚表达时，才添加简短说明。还要写入 goals/<slug>/facts.meta.json，保留每条已接受事实的 id、最终的 text、comment、recommendedAutomatedVerification 和 automatedVerification 值。

如果用户在 UI 中编辑或移除了事实，请直接应用该结果。如果会话被关闭，请停止并告知用户事实审核已关闭。

4. 计划

探索代码库。找出并验证实现每条已接受事实的路径。对于 automatedVerification: true 的事实，必须设计具体的自动化检查，除非你记录了阻碍因素。追踪代码，确定涉及的文件和系统，指出风险和未知事项。反复完善，直到操作顺序明确可靠。

写入 goals/<slug>/plan.md：

• 解决方案概述（简短）
• 有序步骤，以及每步涉及的文件/系统
• 每步的验证方式（具体命令或检查）
• 值得指出的风险或待解决问题

使用 Plannotator 对计划进行审核：

plannotator annotate goals/<slug>/plan.md --gate

如果未获批准，请根据反馈修订并重新提交审核，直至获批。

5. 目标输出

写入 goals/<slug>/goal.md：

• 明确表述目标（1-3 句话）
• 引用 facts.md，作为共同理解
• 引用 plan.md，作为执行计划
• 完成条件

告知用户：

Done! Launch a goal with `/goal goals/<slug>/goal.md`