specifying-gates

指定用户提出的门控项

此技能的运行时机

满足以下任一条件：

1. 某个用户门控任务在其 json:metadata 代码围栏中设置了 "requiresUserSpecification": true，或
2. Agent 执行了“我知道怎么做吗？”自检（参见 executing-plans），并认定验证方式不明确，或
3. 用户手动运行了 /specify-gate <task-id>。

在所有其他情况下——也就是 verifyCommand 明确，且每项 acceptanceCriteria 都有可观察的证明——Agent 会直接执行门控项，而不会调用此技能。

开始时宣布：“我正在使用 specifying-gates 技能，为任务 N 确定验证方式。”

重要——此技能不会做什么

• 不运行验证命令。此技能只负责规格说明。
• 不关闭任务。此技能只会补充元数据；之后 Agent 会返回 executing-plans。
• 不重新进行头脑风暴。设计已经确定；只是缺少某个门控项的实现方式。

输入

目标任务 ID。从命令参数或当前正在进行的用户门控任务中解析。

使用 TaskGet 加载任务，并解析其描述中的 json:metadata 代码围栏。

四个问题

使用 AskUserQuestion——遵循头脑风暴技能的规则，一次只问一个问题。

Q1 — 可观察结果

AskUserQuestion:
  question: "Gate: <task subject>. What exact state proves this works? One line per criterion. 'It works' is not an answer — name a sensor, HTTP status, log line, file presence, or equivalent."
  header: "Gate outcome"
  options:
    - label: "I'll type the criteria"
      description: "Write 1-5 concrete, observable conditions"
    - label: "Copy from task's acceptanceCriteria"
      description: "Use the existing list (only if it's already concrete)"

将用户的自由文本回答保存为 acceptanceCriteria 中的字符串列表。如果某条内容含糊不清（包含“可用”“没问题”“符合预期”“正常”等说法，却没有具体目标），请追问，让用户明确指出可观察的结果。

Q2 — 证明方式

AskUserQuestion:
  question: "How should the agent capture that state?"
  header: "Mechanism"
  options:
    - label: "CLI command"
      description: "A shell command whose output shows the criterion"
    - label: "REST / API call"
      description: "HTTP request, inspect response"
    - label: "Subagent with briefing"
      description: "Dispatch Sonnet or Haiku with a prompt template"
    - label: "Direct inspection"
      description: "Read a file, query an entity, check a log"

如果选择“附带说明的子 Agent”，则在继续之前询问 Q5（分派约定）。

如果用户已经在说明中指出了实时测试样例，则不要提供“干运行跟踪”作为证明方式——将实时命令记录为唯一的 verifyCommand。规格说明是为了锁定决策，不是重新讨论用户已经作出的决定。

Q3 — 范围

AskUserQuestion:
  question: "Run this once, or over multiple targets?"
  header: "Scope"
  options:
    - label: "Once"
      description: "Single execution, single target"
    - label: "Per instance / target"
      description: "Run identically across a list (e.g. all environments)"
    - label: "First on one, then on all"
      description: "Prove it on one target, then roll out to the rest — the classic two-gate pattern"
    - label: "Custom"
      description: "Describe the rule in free text"

将回答保存为 gateScope："once" | "per-target" | "one-then-all" | 自定义字符串。

Q4 — 失败策略

AskUserQuestion:
  question: "If the gate fails, what happens?"
  header: "On failure"
  options:
    - label: "Stop the plan (Recommended)"
      description: "No further tasks until this gate passes"
    - label: "Reopen this task, continue others"
      description: "Mark in_progress, keep the plan moving elsewhere"
    - label: "Log and continue"
      description: "Record failure, proceed — use only for informational gates"

将回答保存为 failurePolicy："stop-plan" | "reopen-continue" | "log-continue"。

Q5（条件项）— 子 Agent 分派约定

仅在 Q2 =“附带说明的子 Agent”时询问。

AskUserQuestion:
  question: "Paste the exact prompt / briefing the subagent should receive. This becomes the dispatch contract — the agent cannot substitute a shorter version at runtime."
  header: "Dispatch brief"
  options:
    - label: "I'll paste it"
      description: "Provide the briefing text"
    - label: "Use instances/<tag>/seed-briefing.md"
      description: "Per-target briefing file already written by a plan task"
    - label: "Generate from task description"
      description: "Build the briefing from the task's Goal + Files + Acceptance Criteria"

将回答保存为 subagentBrief（字符串或文件路径）。

写回

所有问题回答完毕后：

1. 更新任务描述。 使用新字段重写 json:metadata 代码围栏。移除 requiresUserSpecification。保留其他所有内容。调用 TaskUpdate 并传入完整的新描述。

{
  "files": [...],
  "verifyCommand": "<from Q2 — the CLI/API string, or '(subagent)' sentinel>",
  "acceptanceCriteria": ["<from Q1>", ...],
  "userGate": true,
  "tags": ["user-gate"],
  "gateScope": "<from Q3>",
  "failurePolicy": "<from Q4>",
  "subagentBrief": "<from Q5 if applicable>"
}

2. 添加“规格说明”章节到任务描述的易读部分，放在 json:metadata 代码围栏之前：

### Specification (via /specify-gate on <ISO-date>)

- **Outcome:** <Q1>
- **Mechanism:** <Q2>
- **Scope:** <Q3>
- **Failure policy:** <Q4>
- **Subagent brief:** <Q5 if applicable>

3. 同步 .tasks.json。 更新任务条目的描述和元数据，并设置 lastUpdated。

4. 宣布：“规格说明已锁定。将控制权交还给 executing-plans 以运行门控项。”

移交

控制权返回给 executing-plans。Agent 读取更新后的任务，执行 verifyCommand（或使用 subagentBrief 分派子 Agent），捕获输出，并在关闭任务前逐项发布 AC: <criterion> — PROVEN BY <evidence>。

此技能中禁止的操作

• 不要调用 ExitPlanMode 或 EnterPlanMode。
• 不要开始验证。此技能退出后，验证会在 executing-plans 中运行。
• 不要提出超过 4–5 个问题。如果用户的回答不够充分，优先通过一次后续追问重新确认，而不是在初始流程中不断增加问题。
• 除任务描述和 .tasks.json 外，不要向磁盘写入任何内容。不要创建辅助文件。

集成

• 调用来源： executing-plans（自动）、/specify-gate 斜杠命令（手动）。
• 返回至： executing-plans。
• 参考： skills/shared/task-format-reference.md 中的元数据架构。