plannotator-setup-goal

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Setup Goal

设置目标

Turn an idea into a goal package at

goals/<slug>/

through structured discovery, user interview, and codebase exploration.

将想法转化为存储在

goals/<slug>/

下的目标包，过程包括结构化探索、用户访谈和代码库探索。

Phases

阶段

1. Rearticulate

1. 重述目标

State back what the user wants in your own words. If the conversation already has rich context, summarize it. If the goal is bare or vague, do minimal shallow exploration of the codebase to ground your understanding. Keep it to 2-3 sentences. Wait for the user to confirm or correct before continuing.

Create the goal directory once the slug is clear:

bash

mkdir -p goals/<slug>

Use

goals/<slug>/

for both working JSON files and final docs. The JSON files are provenance and iteration state; the markdown files are the human-readable authoritative goal package.

Browser session patience rule: Plannotator goal setup is a user-driven browser session. After launching an interview or facts command, be absolutely patient and keep waiting on the user until they submit, dismiss, or explicitly ask you to stop. Do not close, kill, restart, refresh, or open a second copy just because the UI is idle or the user is taking time. Never close and reopen the session as a way to update state; if a rerun is needed after the prior session ends, update the working JSON file and launch a new command from that file.

Optional: grill first (deep, one-at-a-time interview). Before building the compact interview bundle, suggest a grilling pass whenever the goal is vague or carries many interdependent decisions — and run one whenever the user asks for it ("grill me first"). This is opt-in: for a clear, well-scoped goal, skip it and go straight to the bundle, so grilling never fights the bundle's "fewer, higher-leverage questions" philosophy. When you grill, run the protocol below verbatim, then fold the resolved decisions forward into a higher-quality interview bundle (Phase 2) — or, if grilling fully resolves scope, straight into the fact sheet (Phase 3).

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time.

If a question can be answered by exploring the codebase, explore the codebase instead.

用你自己的话复述用户的需求。如果对话已有丰富上下文，进行总结。如果目标模糊或不明确，对代码库进行最低限度的浅层探索，以夯实你的理解。控制在2-3句话，等待用户确认或修正后再继续。

一旦slug确定，创建目标目录：

bash

mkdir -p goals/<slug>

将

goals/<slug>/

用于工作JSON文件和最终文档。JSON文件记录来源和迭代状态；Markdown文件是供人类阅读的权威目标包。

浏览器会话耐心规则：Plannotator目标设置是由用户驱动的浏览器会话。启动访谈或事实命令后，务必保持耐心，等待用户提交、关闭或明确要求停止。不要因UI闲置或用户耗时就关闭、终止、重启、刷新或打开第二个会话。绝不能通过关闭并重新打开会话来更新状态；若之前的会话结束后需要重新运行，请更新工作JSON文件并从该文件启动新命令。

可选：先进行深度一对一访谈。在构建精简的访谈问卷包之前，当目标模糊或涉及多个相互依赖的决策时，建议先进行一次深度访谈——且当用户要求时（如“先深度访谈我”）必须执行。这是可选操作：对于清晰、范围明确的目标，可跳过此步骤直接进入问卷包环节，因此深度访谈不会违背问卷包“更少、更具影响力的问题”的理念。进行深度访谈时，请严格遵循以下流程，然后将已确定的决策整合到更高质量的访谈问卷包（第2阶段）中——或者，如果深度访谈已完全明确范围，可直接进入事实表环节（第3阶段）。

针对该计划的每个方面对我进行全面访谈，直到我们达成共识。逐一梳理设计树的每个分支，逐个解决决策之间的依赖关系。对于每个问题，提供你的推荐答案。

一次只问一个问题。

如果某个问题可通过探索代码库找到答案，请直接探索代码库。

2. Interview Bundle

2. 访谈问卷包

Build a compact bundle of questions that can derive every "fact" this goal should produce. Package the questions together so the user can answer them quickly in the Plannotator goal setup UI. For each question, include your recommended answer and use options when they make answering faster.

Do not ask obvious confirmation questions. If the answer can be inferred from the user's request, from the conversation, or from shallow codebase exploration, infer it and move on. If an obvious area has meaningful nuance, present the inferred answer as a recommendation with options or a custom "add/correct this" path rather than asking the user to restate the obvious.

Question areas that usually matter:

What the feature/change is
Who it's for
What problem it solves
What behavior changes
What success looks like
What's in and out of scope (the most important area to determine facts)
What edge cases to consider
What constraints or precedent apply

If a question can be answered by exploring the codebase, explore the codebase instead of asking. Only include questions where the user's judgment is actually needed. Prefer fewer, higher-leverage questions over exhaustive obvious ones.

Write the interview bundle before showing it to the user:

goals/<slug>/interview.json

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
    }
  ]
}

Supported

answerMode

values:

text

single

multi

custom

single-custom

multi-custom

Run this as a monitored foreground process and wait patiently for the browser session to finish. The command may appear idle while the user is reading, editing, or asking questions; leave it running:

bash

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

The command returns JSON on stdout with the submitted answers. Write that exact result to

goals/<slug>/interview-result.json

before continuing. A convenient pattern is:

bash

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

If the user revises after the session finishes, update

interview.json

and rerun the command instead of reconstructing the whole bundle from memory. If the session is dismissed, stop and tell the user the goal setup was closed.

Before moving to facts, read every answer and note carefully:

If the user wrote questions, uncertainty, "not sure", "needs context", or similar concerns in an answer or note, stop and address those questions in chat. Do not proceed to facts until the user has enough context or you have rerun a revised interview bundle.
If the user skipped a question with a note, treat the note as intentional feedback, not as an empty answer. Answer the note, refine the question, or make a documented assumption before proceeding.
If the user skipped a question without a note, proceed only if the missing answer is non-blocking; otherwise ask the smallest possible follow-up in chat.

构建一组精简的问题，这些问题可推导出该目标应产生的所有“事实”。将问题打包，以便用户能在Plannotator目标设置UI中快速作答。每个问题需包含你的推荐答案，并在有助于快速作答时提供选项。

不要询问明显的确认类问题。如果答案可从用户请求、对话内容或浅层代码库探索中推断出来，直接推断并继续。如果某个明显领域存在有意义的细微差别，请将推断出的答案作为推荐选项呈现，同时提供选项或自定义“添加/修正”路径，而非让用户重复显而易见的内容。

通常重要的问题领域包括：

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

如果某个问题可通过探索代码库找到答案，请直接探索代码库而非询问用户。仅包含真正需要用户判断的问题。优先选择更少、更具影响力的问题，而非详尽的明显问题。

在向用户展示前撰写访谈问卷包：

goals/<slug>/interview.json

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

。

将此作为受监控的前台进程运行，耐心等待浏览器会话完成。用户阅读、编辑或提问时，命令可能看似处于闲置状态；请保持命令运行：

bash

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

命令会在标准输出返回包含提交答案的JSON。在继续之前，将该结果准确写入

goals/<slug>/interview-result.json

。一种便捷的方式是：

bash

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

如果用户在会话结束后修改内容，请更新

interview.json

并重新运行命令，而非从内存中重建整个问卷包。如果会话被关闭，请停止操作并告知用户目标设置已关闭。

进入事实环节前，请仔细阅读所有答案并注意：

如果用户在答案或备注中提出问题、表示不确定、“不清楚”、“需要上下文”或类似内容，请停止并在聊天中解决这些问题。在用户获得足够上下文或你重新运行修订后的访谈问卷包之前，不要进入事实环节。
如果用户跳过某个问题并留下备注，请将该备注视为有意反馈，而非空答案。在继续之前，请回应备注、优化问题或做出有记录的假设。
如果用户跳过某个问题且未留备注，仅当缺失的答案不影响后续操作时才可继续；否则在聊天中提出尽可能简短的跟进问题。

3. Fact Sheet

3. 事实表

A fact is a simple description of each outcome of a goal. It should be easily testable and verifiable. A fact may describe the function of a specific feature or aspect of a system. A fact may determine specific UI and UX. Again, a fact is literally anything that can be tested and verified in automated or manual testing. Keep fact language simple. In a way, a fact sheet is a design spec, but less verbose & using language the human user can easily visualize & rationalize.

Prepare a facts review bundle from

goals/<slug>/interview-result.json

. Each fact should include whether automated verification is recommended and preselected.

Write the facts review bundle before showing it to the user. If revising after a prior facts pass, start from

facts-review.json

and

facts-result.json

, include previously accepted facts with

"accepted": true

, and preserve their state.

goals/<slug>/facts-review.json

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
    }
  ]
}

Run this as a monitored foreground process and wait patiently for the browser session to finish. The command may appear idle while the user is reviewing, editing, or asking questions; leave it running:

bash

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

The command returns JSON on stdout with accepted/edited/removed facts plus automated verification selections. Write that exact result to

goals/<slug>/facts-result.json

. A convenient pattern is:

bash

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

Write

goals/<slug>/facts.md

as a flat readable list of accepted facts. Each fact is one line; add a minimal note only when the fact cannot be stated clearly on its own. Also write

goals/<slug>/facts.meta.json

preserving each accepted fact's

id

, final

text

comment

recommendedAutomatedVerification

, and

automatedVerification

value.

If the user edits or removes facts in the UI, apply that result directly. If the session is dismissed, stop and tell the user the facts review was closed.

事实是对目标每个成果的简单描述，应易于测试和验证。事实可描述特定功能或系统某一方面的作用，也可确定具体的UI和UX。简言之，事实是任何可通过自动化或手动测试进行验证的内容。保持事实表述简洁。从某种意义上说，事实表是一份设计规范，但更简洁，且使用人类用户易于可视化和理解的语言。

根据

goals/<slug>/interview-result.json

准备事实审核包。每个事实需包含是否建议并预选自动化验证。

在向用户展示前撰写事实审核包。如果在之前的事实环节后进行修订，请从

facts-review.json

和

facts-result.json

开始，包含已接受的事实并标记

"accepted": true

，同时保留其状态。

goals/<slug>/facts-review.json

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
    }
  ]
}

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

bash

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

命令会在标准输出返回包含已接受/编辑/删除的事实以及自动化验证选择的JSON。将该结果准确写入

goals/<slug>/facts-result.json

。一种便捷的方式是：

bash

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. Plan

4. 执行计划

Explore the codebase. Discover and validate implementation paths toward each accepted fact. Treat facts with

automatedVerification: true

as requiring concrete automated checks unless you document a blocker. Trace through code, identify files and systems involved, surface risks and unknowns. Refine until you have a confident order of operations.

Write

goals/<slug>/plan.md

Solution approach (brief)
Ordered steps with the files/systems each touches
Verification for each step (concrete commands or checks)
Risks or open questions worth flagging

Gate the plan with Plannotator:

bash

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

If denied, revise from feedback and re-gate until approved.

探索代码库，发现并验证实现每个已接受事实的路径。将标记

automatedVerification: true

的事实视为需要具体自动化检查的内容，除非你记录了障碍。追踪代码，确定涉及的文件和系统，指出风险和未知事项。不断完善，直到你确定一个可靠的操作顺序。

编写

goals/<slug>/plan.md

：

解决方案方法（简要说明）
按顺序排列的步骤，以及每个步骤涉及的文件/系统
每个步骤的验证方式（具体命令或检查方法）
需要标记的风险或未解决问题

使用Plannotator审核执行计划：

bash

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

如果未通过审核，根据反馈修订并重新提交审核，直到获得批准。

5. Goal Output

5. 目标输出

Write

goals/<slug>/goal.md

The articulated goal (1-3 sentences)
Reference to
```
facts.md
```
as the shared understanding
Reference to
```
plan.md
```
as the execution plan
Done condition

Tell the user:

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

编写

goals/<slug>/goal.md

：

重述的目标（1-3句话）
引用
```
facts.md
```
作为共识依据
引用
```
plan.md
```
作为执行计划
完成条件

告知用户：

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