clarifying-assumptions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clarifying Assumptions

假设澄清

Purpose

用途

Act as a structured interviewer that walks the user through open questions, assumptions, and decisions in the task plan — using progressive disclosure. Three goals:

Resolve ambiguity so downstream execution is unblocked.
Educate the user on the agent's reasoning so they can steer confidently.
Avoid premature questions — never ask about tasks that have not been reached yet, because by the time we get there, the answers may have changed.

充当结构化的访谈者，通过渐进式披露机制引导用户梳理任务计划中的未决问题、假设和决策。本技能有三个核心目标：

消除歧义，为后续执行环节扫清障碍。
向用户同步Agent的推理逻辑，让用户可以放心地把控方向。
避免提前提问——永远不要询问还未进入执行阶段的任务相关问题，因为到执行节点时，答案可能已经发生变化。

Progressive Disclosure — The Core Principle

渐进式披露——核心原则

Traditional clarification asks ALL questions upfront. This is wasteful because:

Answers to later questions often depend on what happens during earlier tasks.
Context gained during execution changes the relevance of questions.
Users waste time answering questions about tasks that may not even happen.
Some questions become irrelevant as the codebase evolves through execution.

Instead, this skill uses a two-tier disclosure model:

传统的澄清流程会一次性询问所有问题，这种做法效率很低，原因如下：

后期问题的答案往往取决于早期任务的执行结果。
执行过程中获取的上下文会改变问题的相关性。
用户可能会浪费时间回答那些根本不会执行的任务的相关问题。
随着代码库在执行过程中不断演进，部分问题会变得无关紧要。

因此，本技能采用双层披露模型：

Tier 1 — Phase 3 (Upfront Clarification)

第一层——第3阶段（前置澄清）

During the initial clarification phase, ask ONLY:

Cross-cutting questions that affect the entire plan (e.g., "Which API version should we use?" or "What authentication strategy?"). These are blocking for planning and must be resolved before any execution begins.
Assumptions that affect architecture — confirmed or revised now because changing them later would require reworking completed tasks.
Validation report FAILs — these block execution entirely.
Questions for Task 1 only — since Task 1 will be executed first, its per-task questions are relevant now. All other per-task questions are deferred.

Do NOT ask per-task questions for Tasks 2, 3, 4, etc. during Phase 3. Tag them as

[DEFERRED — will ask before Task N execution]

in the manifest.

在初始澄清阶段，仅询问以下类型的问题：

影响全局的跨领域问题（例如“我们应该使用哪个API版本？”或者“采用什么认证策略？”）。这类问题会阻塞整个规划流程，必须在执行开始前解决。
影响架构的假设——需要在这个阶段确认或修订，因为后续修改这些内容会导致已经完成的任务需要返工。
验证报告不通过项——这些问题会完全阻塞执行流程。
仅针对任务1的问题——因为任务1会最先执行，其专属问题当前是相关的。所有其他任务的专属问题都将延后处理。

在第3阶段不要询问任务2、3、4等其他任务的专属问题，在清单中将这些问题标记为

[DEFERRED — will ask before Task N execution]

（延后处理——将在任务N执行前询问）。

Tier 2 — Phase 5 (Just-In-Time Clarification)

第二层——第5阶段（即时澄清）

Before each task execution in Phase 5, the orchestrator checks whether the task about to execute has unresolved questions or assumptions. If it does, the orchestrator invokes this skill in just-in-time mode with the specific task number.

In just-in-time mode:

Only ask questions tagged for the specific task about to execute.
Review whether any deferred questions have become irrelevant due to decisions made or code changes during earlier task executions.
Present questions that are still relevant.

Mark irrelevant questions as

[RESOLVED — no longer applicable: <reason>]

在第5阶段每个任务执行前，编排器会检查待执行任务是否存在未解决的问题或假设。如果存在，编排器会传入指定的任务编号，以即时模式调用本技能。

在即时模式下：

仅询问标记为待执行任务相关的问题。
检查所有延后的问题是否因为前期任务执行过程中做出的决策或代码变更而变得无关紧要。
仅展示仍然相关的问题。
将无关问题标记为
```
[RESOLVED — no longer applicable: <reason>]
```
（已解决——不再适用：<原因>）。

Platform Adaptation

平台适配

This skill runs across multiple environments (Claude.ai, Claude Code CLI, Cursor IDE, OpenCode CLI, and others). The SKILL.md format is a cross-platform open standard, but tool availability differs by environment.

Interactive input: Most platforms provide an interactive selection tool (Claude.ai has

ask_user_input

, Claude Code has

AskUserQuestion

, Cursor has its own ask-question tool). At the start of execution, check whether any interactive input tool is available. If one exists, use it for every discrete choice. If none is available, fall back to numbered text options and ask the user to reply with a number. Both paths work — the goal is minimal friction.

Visual context: Prefer markdown tables as the default visual (universally supported across all platforms). Use mermaid diagrams only when the environment renders them inline (Claude.ai and Cursor do; OpenCode's TUI does not) and the question genuinely involves architecture, data flow, or dependency structure. ASCII diagrams are an acceptable fallback in terminal environments.

本技能可在多个环境中运行（Claude.ai、Claude Code CLI、Cursor IDE、OpenCode CLI等）。SKILL.md格式是跨平台的开放标准，但不同环境的可用工具存在差异。

交互式输入： 大多数平台都提供交互式选择工具（Claude.ai有

ask_user_input

，Claude Code有

AskUserQuestion

，Cursor有自己的提问工具）。执行开始时，先检查是否存在可用的交互式输入工具。如果有，每次离散选择都使用该工具；如果没有，降级为编号文本选项，要求用户回复对应数字。两种方式都有效，目标是尽可能降低使用摩擦。

可视化上下文： 默认优先使用markdown表格（所有平台都支持）。仅当环境支持内联渲染Mermaid图（Claude.ai和Cursor支持，OpenCode的TUI不支持），且问题确实涉及架构、数据流或依赖结构时，才使用Mermaid图。终端环境下可以使用ASCII图作为备选方案。

Inputs

输入项

Input	Source	Required	Example
`TICKET_KEY`	User / `$ARGUMENTS`	Yes	`JNS-6065`
`MODE`	Orchestrator	No	`upfront` or `just-in-time`
`TASK_NUMBER`	Orchestrator	No	`3` (required if MODE is `just-in-time` )

The task plan file must already exist at

docs/<TICKET_KEY>-tasks.md

. If it does not, tell the user to run the planning-jira-tasks skill first.

Default

MODE

upfront

when called during Phase 3.

输入项	来源	是否必填	示例
`TICKET_KEY`	用户 / `$ARGUMENTS`	是	`JNS-6065`
`MODE`	编排器	否	`upfront` （前置）或 `just-in-time` （即时）
`TASK_NUMBER`	编排器	否	`3` （如果MODE为 `just-in-time` 则必填）

任务计划文件必须已经存在于

docs/<TICKET_KEY>-tasks.md

路径下。如果文件不存在，告知用户需要先运行planning-jira-tasks技能。

在第3阶段调用时，默认

MODE

为

upfront

。

Input contract (from upstream skill)

输入契约（来自上游技能）

The input file must contain these sections (produced by

planning-jira-tasks

). If any are missing, the plan was not generated correctly — stop and ask the user to re-run planning.

Required section	Used for
`## Assumptions and Constraints`	Items to present for user confirmation
`## Cross-Cutting Open Questions`	High-impact questions that affect multiple tasks
`## Tasks` with per-task subsections	Per-task questions and implicit assumptions
`## Validation Report`	WARN/FAIL items become clarification questions
`## Dependency Graph`	Impact maps for dependency-related questions

输入文件必须包含以下部分（由

planning-jira-tasks

生成）。如果缺少任何部分，说明计划生成不正确——停止执行，要求用户重新运行规划流程。

必填部分	用途
`## Assumptions and Constraints` （假设与约束）	展示给用户确认的项
`## Cross-Cutting Open Questions` （跨领域未决问题）	影响多个任务的高优先级问题
`## Tasks` （任务）带每个任务的子部分	每个任务的专属问题和隐含假设
`## Validation Report` （验证报告）	警告/不通过项会转化为澄清问题
`## Dependency Graph` （依赖图）	依赖相关问题的影响映射

Output

输出

The same task plan file at

docs/<TICKET_KEY>-tasks.md

, updated in-place, with:

A
```
## Decisions Log
```
table appended (or updated if it already exists)
Assumptions annotated (
```
✅ Confirmed
```
/
```
❌ Revised: <new text>
```
)
Per-task questions resolved (
```
~~<question>~~ → <answer>
```
)
Updated
```
Implementation notes
```
where answers changed the approach

Deferred questions tagged with

[DEFERRED — will ask before Task N execution]

路径为

docs/<TICKET_KEY>-tasks.md

的同一个任务计划文件，会被原地更新，包含以下内容：

追加（或更新，如果已存在）
```
## Decisions Log
```
（决策日志）表格
标记假设状态（
```
✅ Confirmed
```
（已确认）/
```
❌ Revised: <new text>
```
（已修订：<新内容>））
解决每个任务的问题（
```
~~<question>~~ → <answer>
```
（<问题> → <答案>））
如果答案改变了实现方案，更新
```
Implementation notes
```
（实现说明）

延后的问题会被标记为

[DEFERRED — will ask before Task N execution]

Output contract (consumed by downstream skills)

输出契约（供下游技能使用）

Addition	Required by	Why
`## Decisions Log` table	creating-jira-subtasks	Subtask descriptions reflect resolved decisions
Annotated assumptions	executing-jira-task	Executor needs confirmed assumptions, not open Qs
Resolved per-task questions	executing-jira-task	Pre-flight check verifies no unresolved questions
Updated `Implementation notes` (where approach changed)	executing-jira-task	Executor follows the updated approach
Deferred question tags	orchestrator (Phase 5)	Orchestrator knows which questions to ask before each task

新增内容	被谁使用	原因
`## Decisions Log` （决策日志）表格	creating-jira-subtasks	子任务描述会体现已解决的决策
已标记状态的假设	executing-jira-task	执行器需要已确认的假设，而非未决问题
已解决的任务专属问题	executing-jira-task	前置检查会验证没有未解决的问题
已更新的 `Implementation notes` （实现说明）（如果方案有变更）	executing-jira-task	执行器会遵循更新后的方案
延后问题标记	编排器（第5阶段）	编排器知道每个任务执行前需要询问哪些问题

Subagent Registry

子代理注册表

Subagent	Path	Purpose
`decision-recorder`	`./subagents/decision-recorder.md`	Applies all file edits (Decisions Log, annotations, tags) + validates

Before dispatching, read the subagent file to understand its input/output contract. The path is relative to this skill's directory.

Why only file writes are delegated: This skill is conversational — it needs the user's full conversation history for multi-turn Q&A. The Q&A loop and plan parsing run inline because the skill needs manifest content in context to ask questions. File writes are delegated because they are separable from the conversation and would pollute the context with raw file I/O.

子代理	路径	用途
`decision-recorder`	`./subagents/decision-recorder.md`	执行所有文件编辑（决策日志、标注、标记）+ 验证

调度前，请阅读子代理文件了解其输入输出契约。路径是相对于本技能目录的相对路径。

为什么仅将文件写入操作委托出去： 本技能是对话式的——需要用户的完整对话历史来完成多轮问答。问答循环和计划解析会内联运行，因为技能需要清单内容作为上下文来提问。文件写入操作被委托出去，是因为它们可以与对话分离，且原始文件I/O操作会污染上下文。

Core Principles

核心原则

These three principles shape every interaction in this skill. They're ordered by impact — if you remember nothing else, remember these.

这三条原则决定了本技能的每一次交互，按影响优先级排序——就算其他内容都记不住，也要记住这几条。

1. Ask only what is relevant NOW

1. 仅询问当前相关的内容

upfront

mode: ask cross-cutting questions, architectural assumptions, validation failures, and Task 1 questions only. Tag everything else as deferred.

just-in-time

mode: ask only questions for the specific task about to execute. Discard questions that are no longer relevant.

If an answer reveals a new question about a FUTURE task, do not ask it now. Tag it as deferred for that task. If the new question is about the CURRENT task or is cross-cutting, ask it immediately.

在

upfront

（前置）模式下：仅询问跨领域问题、架构假设、验证不通过项和任务1的问题。所有其他内容标记为延后处理。

在

just-in-time

（即时）模式下：仅询问待执行特定任务的相关问题，丢弃不再相关的问题。

如果某个答案引出了关于未来任务的新问题，不要现在提问，将其标记为对应任务的延后问题。如果新问题与当前任务相关或属于跨领域问题，立即提问。

2. Use interactive selection for every discrete choice

2. 所有离散选择都使用交互式选择

When the user must pick from a set of options, use the most frictionless input method available:

If an interactive input tool is available (e.g.,
```
ask_user_input
```
,
```
AskUserQuestion
```
, or equivalent): Use it. Single-select for one answer from 2-4 options, multi-select for multiple valid answers, rank/prioritize for ordering.

If no interactive tool is available: Present numbered options and ask the user to reply with a number. Example:

1. Repository pattern
2. Direct database access
3. CQRS
4. Other (I'll describe)

Reply with a number (or type your own answer):

When a question has discrete options plus a possible free-text path, present the options first. If the user picks "Other," follow up for details.

For confirmation questions (assumptions), use:

1. ✅ Confirm as-is

2. ❌ Revise

3. ⏭️ Skip

当用户需要从一组选项中选择时，使用可用的最低摩擦输入方式：

如果有可用的交互式输入工具（例如
```
ask_user_input
```
、
```
AskUserQuestion
```
或等效工具）：使用它。2-4个选项的单选用单选工具，允许多个正确答案的用多选工具，需要排序的用排名/优先级工具。

如果没有可用的交互式工具： 展示编号选项，要求用户回复对应数字。示例：

1. Repository pattern
2. Direct database access
3. CQRS
4. 其他（我会自行描述）

请回复对应数字（或输入你自己的答案）：

当问题有离散选项同时支持自由文本输入时，先展示选项。如果用户选择“其他”，再追问细节。

对于假设确认类问题，使用：

1. ✅ 确认内容无误

、

2. ❌ 修订

、

3. ⏭️ 跳过

。

3. Give visual context proportional to the question's complexity

3. 提供与问题复杂度匹配的可视化上下文

Every question should have enough context for the user to answer confidently. The right amount depends on what's being asked:

Question type	Appropriate context
Simple confirmation	1-2 sentences on what the assumption is and where it came from
Choice between technical options	Comparison table showing trade-offs, or a code snippet showing the difference
Architecture / data flow decision	Diagram (mermaid or ASCII) showing how options differ
Question with downstream impact	Brief impact note: "This affects Tasks 3, 5, and 7"

Don't pad simple confirmations with diagrams they don't need. Do invest in visuals when the question involves trade-offs, structural differences, or cascading effects. The goal is understanding, not decoration.

Choosing the right visual:

Visual type	Best for	Format
Markdown table	Comparing options side by side (works everywhere)	Markdown table
Code snippet	When the question affects specific code, configs, APIs	Fenced code block with lang
Mermaid diagram	Architecture, data flow, dependencies (if env supports)	Mermaid code block
Before / after	When the answer changes the plan structure	Two code blocks or tables

每个问题都应该提供足够的上下文，让用户可以放心作答。合适的上下文量取决于问题本身：

问题类型	合适的上下文
简单确认	1-2句话说明假设内容和来源
技术方案选择	展示权衡对比表，或体现差异的代码片段
架构/数据流决策	展示不同选项差异的图表（Mermaid或ASCII）
有下游影响的问题	简短的影响说明：“这会影响任务3、5和7”

不要给简单的确认问题配上不需要的图表。当问题涉及权衡、结构差异或连锁影响时，要花精力做好可视化。目标是帮助理解，而非装饰。

选择合适的可视化形式：

可视化类型	适用场景	格式
Markdown表格	并排对比选项（所有环境都适用）	Markdown表格
代码片段	问题影响特定代码、配置、API时使用	带语言标注的 fenced 代码块
Mermaid 图	架构、数据流、依赖（如果环境支持）	Mermaid代码块
前后对比	答案会改变计划结构时使用	两个代码块或表格

Execution — Upfront Mode (Phase 3)

执行流程——前置模式（第3阶段）

Phase 1 — Build and present the question manifest

阶段1——构建并展示问题清单

1a. Read and categorize all items

1a. 读取并分类所有项

Read

docs/<TICKET_KEY>-tasks.md

and build the complete list of items needing user input:

Category	Where to find them	Tier
Validation FAILs	`## Validation Report` — unresolved FAIL items	Tier 1
Cross-cutting questions	`## Cross-Cutting Open Questions` section	Tier 1
Architectural assumptions	`## Assumptions and Constraints` section	Tier 1
Task 1 questions	`Questions to answer before starting` in Task 1	Tier 1
Task 2+ questions	`Questions to answer before starting` in Tasks 2+	DEFERRED
Task 2+ assumptions	Implicit assumptions in Tasks 2+ `Implementation notes`	DEFERRED
Dependency risks	`Dependencies / prerequisites` that seem uncertain	Tier 1 if affects Task 1, else DEFERRED
Validation warnings	`## Validation Report` — WARN items	Tier 1 if cross-cutting, else DEFERRED

读取

docs/<TICKET_KEY>-tasks.md

，构建需要用户输入的完整项列表：

分类	查找位置	层级
验证不通过项	`## Validation Report` （验证报告）——未解决的不通过项	第一层
跨领域问题	`## Cross-Cutting Open Questions` （跨领域未决问题）部分	第一层
架构假设	`## Assumptions and Constraints` （假设与约束）部分	第一层
任务1问题	任务1中的 `Questions to answer before starting` （开始前需要回答的问题）	第一层
任务2及以后的问题	任务2及以后的 `Questions to answer before starting` （开始前需要回答的问题）	延后处理
任务2及以后的假设	任务2及以后的 `Implementation notes` （实现说明）中的隐含假设	延后处理
依赖风险	存在不确定性的 `Dependencies / prerequisites` （依赖/前置条件）	如果影响任务1则为第一层，否则延后处理
验证警告	`## Validation Report` （验证报告）——警告项	如果是跨领域问题则为第一层，否则延后处理

1b. Prioritize Tier 1 items

1b. 优先级排序第一层项

Order Tier 1 items so blocking issues surface first:

Unresolved FAILs from the validation report (they block execution)
Cross-cutting questions (they unblock the most tasks)
Assumptions affecting architectural decisions
Task 1 questions, ordered by priority
Cross-cutting validation warnings

对第一层项进行排序，让阻塞问题最先展示：

验证报告中的未解决不通过项（会阻塞执行）
跨领域问题（会解锁最多的任务）
影响架构决策的假设
任务1问题，按优先级排序
跨领域验证警告

1c. Present the manifest

1c. 展示清单

Show the complete numbered list to the user, clearly marking deferred items:

markdown

undefined

向用户展示完整的编号列表，明确标记延后处理的项：

markdown

undefined

Question Manifest for <TICKET_KEY>

<TICKET_KEY> 问题清单

I've analyzed the task plan and found <N> items total. <M> questions are relevant now (Tier 1). The remaining <N-M> will be asked just before their respective tasks are executed.

我已分析任务计划，共发现 <N> 个项。当前有 <M> 个问题 是相关的（第一层）。剩余 <N-M> 个问题 会在对应任务执行前即时询问。

Questions for now (Tier 1)

当前需要处理的问题（第一层）

#	Category	Short description	Affects tasks	Input type
1	🔴 Blocking	Missing API version specification	3, 5, 7	Single select
2	🟡 Cross-cutting	Authentication strategy	2, 4, 6	Single select
3	🔵 Assumption	Database migration strategy	1	Confirm/revise
4	⚪ Task 1 question	Caching layer needed?	1	Yes/No

序号	分类	简短描述	影响任务	输入类型
1	🔴 阻塞问题	缺少API版本 specification	3, 5, 7	单选
2	🟡 跨领域问题	认证策略	2, 4, 6	单选
3	🔵 假设	数据库迁移策略	1	确认/修订
4	⚪ 任务1问题	是否需要缓存层？	1	是/否

Deferred questions (will ask before each task)

延后处理的问题（将在对应任务执行前询问）

Task	# deferred questions	Will ask before executing task
2	2	Before Task 2 execution
3	1	Before Task 3 execution
5	3	Before Task 5 execution

Estimated time for Tier 1: ~<N> minutes (most questions have pre-defined options).

No surprise questions during this session. Deferred questions will be asked one task at a time during execution, when context is fresh.


Then ask whether the user is ready to start, or wants to reorder, skip, or
add anything.

任务	延后问题数量	询问时机
2	2	任务2执行前
3	1	任务3执行前
5	3	任务5执行前

第一层问题预计耗时： ~<N> 分钟（大多数问题都有预定义选项）。

本次会话不会出现意外问题。延后问题会在执行过程中逐个任务询问，那时上下文也会更清晰。


然后询问用户是否准备好开始，或者是否想要重新排序、跳过或添加内容。

Phase 2 — Walk through Tier 1 questions one at a time

阶段2——逐个梳理第一层问题

For each question in the Tier 1 manifest:

针对第一层清单中的每个问题：

2a. Show progress

2a. 展示进度

Question <current>/<total Tier 1> — [<category emoji> <category>]

问题 <当前序号>/<第一层总数量> — [<分类emoji> <分类>]

2b. Provide context (proportional to complexity — see Principle 3)

2b. 提供上下文（与复杂度匹配——参考原则3）

Include:

What this relates to: 1-2 sentences on where in the plan this came from.
Visual context: Table, code snippet, diagram, or impact note — whatever makes the difference between options most obvious.
Why this matters: 1-2 sentences on what changes downstream (skip if the impact is obvious or self-contained).

包含：

关联内容： 1-2句话说明该问题来自计划中的哪个部分。
可视化上下文： 表格、代码片段、图表或影响说明——任何能让选项差异更清晰的内容。
重要性： 1-2句话说明会对下游产生什么影响（如果影响很明显或只影响当前内容可以省略）。

2c. Ask using the best available input method (see Principle 2)

2c. 使用最佳可用输入方式提问（参考原则2）

For discrete options, use interactive selection or numbered options. For free-text questions, ask in plain text but still provide context first.

对于离散选项，使用交互式选择或编号选项。对于自由文本问题，先提供上下文再用纯文本提问。

2d. Record the answer

2d. 记录答案

After the user responds:

Acknowledge in one sentence.
State downstream impact if the answer changes something — e.g., "This means Task 3's implementation notes will shift from REST to GraphQL."
Move on. Don't elaborate or re-ask.

On "skip": Record as unresolved with the fallback assumption. Move on.

On "revise": Follow up with: "What should the revised assumption be?" Record the new text.

On an answer that reveals a new question about the CURRENT task or cross-cutting: Don't ask it now. Say: "Your answer raised a new consideration. I'm adding it as Question <N+1>." When the original manifest is done, present the new questions for confirmation first.

On an answer that reveals a new question about a FUTURE task: Tag it as deferred. Say: "This raises a question for Task <N>. I'll ask it when we get there."

用户回复后：

用一句话确认收到。
说明下游影响（如果答案改变了某些内容）——例如“这意味着任务3的实现说明会从REST调整为GraphQL”。
继续下一个问题。不要详细阐述或重复提问。

如果用户选择“跳过”： 记录为未解决，使用默认假设，继续下一个问题。

如果用户选择“修订”： 追问“修订后的假设应该是什么？”，记录新内容。

如果答案引出了当前任务或跨领域的新问题： 不要现在提问，告知用户：“你的回答引出了一个新的考虑点，我会将其添加为第<N+1>个问题。” 原始清单处理完成后，先展示新问题供确认。

如果答案引出了未来任务的新问题： 标记为延后处理，告知用户：“这引出了任务<N>的一个问题，我们到对应阶段再确认。”

Phase 3 — Delegate file updates and summarize

阶段3——委托文件更新并总结

3a. Dispatch

decision-recorder

3a. 调度

decision-recorder

After all Tier 1 questions have been walked through, collect the accumulated decisions, deferred questions, and implementation note updates into structured lists (see the

decision-recorder

subagent's input contract for the exact format).

Read

./subagents/decision-recorder.md

and dispatch the subagent with:

```
TICKET_KEY
```
```
MODE=upfront
```
```
DECISIONS
```
— the full list of resolved decisions from Phase 2
```
DEFERRED_QUESTIONS
```
— questions tagged for future tasks
```
IMPLEMENTATION_UPDATES
```
— any implementation notes that changed due to answers

The subagent handles all file edits:

Appends or updates the
```
## Decisions Log
```
table.
Annotates assumptions (✅ Confirmed / ❌ Revised / ⏭️ Skipped).
Strikes through resolved questions with answers.

Tags deferred questions with

[DEFERRED — will ask before Task N execution]

Updates
```
Implementation notes
```
where answers changed the approach.
Validates all updates were applied correctly.
Returns a validation summary.

所有第一层问题梳理完成后，将积累的决策、延后问题和实现说明更新整理为结构化列表（具体格式参考

decision-recorder

子代理的输入契约）。

读取

./subagents/decision-recorder.md

，传入以下参数调度子代理：

```
TICKET_KEY
```
```
MODE=upfront
```
```
DECISIONS
```
——阶段2中所有已解决的决策的完整列表
```
DEFERRED_QUESTIONS
```
——标记为未来任务的延后问题
```
IMPLEMENTATION_UPDATES
```
——因答案变更需要更新的实现说明

子代理会处理所有文件编辑：

追加或更新
```
## Decisions Log
```
（决策日志）表格。
标记假设状态（✅ 已确认 / ❌ 已修订 / ⏭️ 已跳过）。
给已解决的问题添加删除线并附上答案。

给延后问题标记

[DEFERRED — will ask before Task N execution]

。

如果答案改变了方案，更新
```
Implementation notes
```
（实现说明）。
验证所有更新已正确应用。
返回验证总结。

3b. Handle the result

3b. 处理结果

Check the subagent's summary:

If validation is PASS: Proceed to the final summary.
If validation is WARN: Review the warnings. If updates could not be applied (e.g., question text not found), note this in the user summary. The warnings do not block — they are informational.

检查子代理的总结：

如果验证通过： 进入最终总结环节。
如果验证有警告： 查看警告内容。如果更新未能应用（例如找不到问题文本），在用户总结中说明。警告不会阻塞流程——仅作为参考信息。

3c. Final summary

3c. 最终总结

markdown

undefined

markdown

undefined

Clarification Complete (Tier 1) — <TICKET_KEY>

澄清完成（第一层）—— <TICKET_KEY>

Metric	Count
Tier 1 questions resolved	<N>
Assumptions confirmed	<N>
Assumptions revised	<N>
Items skipped	<N>
Questions deferred	<N>
New questions added	<N>

Key changes to the plan:

<list material changes, if any>

Deferred questions: <N> questions will be asked just-in-time before their respective tasks are executed.

The task plan at

docs/<TICKET_KEY>-tasks.md

has been updated with all decisions.


Then ask what's next:

Create subtasks in Jira
Review the updated plan first
I have more questions

---

指标	数量
已解决的第一层问题	<N>
已确认的假设	<N>
已修订的假设	<N>
已跳过的项	<N>
延后的问题	<N>
新增的问题	<N>

计划的关键变更：

<列出实质性变更，如果有的话>

延后的问题： <N> 个问题会在对应任务执行前即时询问。

路径为

docs/<TICKET_KEY>-tasks.md

的任务计划已更新所有决策。


然后询问下一步操作：

在Jira中创建子任务
先查看更新后的计划
我还有其他问题

---

Execution — Just-In-Time Mode (Phase 5, before each task)

执行流程——即时模式（第5阶段，每个任务执行前）

This mode is invoked by the orchestrator before executing a specific task.

本模式由编排器在执行特定任务前调用。

1. Load deferred questions for this task

1. 加载该任务的延后问题

Read

docs/<TICKET_KEY>-tasks.md

and extract:

Questions tagged

[DEFERRED — will ask before Task <TASK_NUMBER> execution]

Any unresolved assumptions specific to this task
Any new questions added by previous task executions

读取

docs/<TICKET_KEY>-tasks.md

，提取以下内容：

标记为

[DEFERRED — will ask before Task <TASK_NUMBER> execution]

的问题

该任务专属的任何未解决假设
前期任务执行过程中新增的任何问题

2. Filter for relevance

2. 过滤相关性

Review each deferred question against the CURRENT state of the codebase and plan. Some questions may no longer be relevant because:

A decision made during a previous task execution resolved the question.
The codebase has changed in a way that makes one option clearly correct.
The task's scope has narrowed or shifted during earlier execution.

Mark irrelevant questions as:

[RESOLVED — no longer applicable: <reason>]

对照代码库和计划的当前状态，检查每个延后问题。部分问题可能已经不再相关，原因包括：

前期任务执行过程中做出的决策已经解决了该问题。
代码库的变更已经让某个选项显然是正确选择。
任务范围在前期执行过程中已经收窄或调整。

将无关问题标记为：

[RESOLVED — no longer applicable: <reason>]

（已解决——不再适用：<原因>）。

3. Present remaining questions

3. 展示剩余问题

If questions remain:

markdown

undefined

如果还有未解决的问题：

markdown

undefined

Just-In-Time Clarification — Task <N>: <Title>

即时澄清——任务 <N>: <标题>

Before executing this task, <M> question(s) need your input:

#	Short description	Input type
1	<description>	Single select
2	<description>	Confirm/revise


Walk through each question using the same one-at-a-time protocol from
upfront mode (progress indicator, context, interactive selection, acknowledge).

If no questions remain (all were resolved or became irrelevant):

All deferred questions for Task <N> have been resolved by prior decisions or are no longer applicable. Ready to execute.

undefined

执行该任务前，有 <M> 个问题需要你确认：

序号	简短描述	输入类型
1	<描述>	单选
2	<描述>	确认/修订


使用与前置模式相同的逐个处理流程梳理每个问题（进度指示器、上下文、交互式选择、确认收到）。

如果没有剩余问题（所有问题都已解决或不再相关）：

任务<N>的所有延后问题都已通过之前的决策解决，或不再适用。准备好执行。

undefined

4. Delegate file updates

4. 委托文件更新

Dispatch

decision-recorder

with:

```
TICKET_KEY
```
```
MODE=jit
```
```
TASK_NUMBER=<N>
```
```
DECISIONS
```
— any decisions resolved during step 3
```
IMPLEMENTATION_UPDATES
```
— any implementation notes that changed
```
RESOLVED_IRRELEVANT
```
— questions marked irrelevant in step 2 (with reasons)

The subagent handles all file edits:

Updates the Decisions Log with new entries (marking
```
Phase resolved
```
as
```
Phase 5 — Task <N>
```
).
Resolves the task's
```
Questions to answer before starting
```
section.

Tags irrelevant questions with

[RESOLVED — no longer applicable: <reason>]

Updates
```
Implementation notes
```
if any answers changed the approach.
Validates all updates were applied correctly.

If the subagent reports warnings (updates that could not be applied), note them but do not block — they are informational.

传入以下参数调度

decision-recorder

：

```
TICKET_KEY
```
```
MODE=jit
```
```
TASK_NUMBER=<N>
```
```
DECISIONS
```
——步骤3中解决的所有决策
```
IMPLEMENTATION_UPDATES
```
——任何变更的实现说明
```
RESOLVED_IRRELEVANT
```
——步骤2中标记为无关的问题（附带原因）

子代理会处理所有文件编辑：

用新条目更新决策日志（将
```
Phase resolved
```
（解决阶段）标记为
```
Phase 5 — Task <N>
```
（第5阶段——任务<N>））。
解决任务的
```
Questions to answer before starting
```
（开始前需要回答的问题）部分。

给无关问题标记

[RESOLVED — no longer applicable: <reason>]

。

如果任何答案改变了方案，更新
```
Implementation notes
```
（实现说明）。
验证所有更新已正确应用。

如果子代理报告警告（更新未能应用），说明警告内容但不要阻塞流程——仅作为参考信息。

Behavioral Guardrails

行为约束

One question per message. Never batch multiple questions in a single turn.
The manifest is the source of truth. Every question comes from it. New questions get added to it before being asked.
Defer, don't discard. Questions for future tasks are tagged as deferred, not deleted. They will be reviewed for relevance when their task comes up.
Be a teacher, not an interrogator. Context should help the user understand the problem space, not just answer your question.
Respect "skip." Note the fallback, move on, no pressure.
Stay neutral on options. If you have a recommendation, frame it as "I'd lean toward X because..." not "You should do X."
Keep each question block scannable — readable in under 30 seconds. Let the visuals carry the weight; don't duplicate them in prose.
Never ask about what hasn't happened yet. If a question's relevance depends on the outcome of a future task, it must be deferred.

每条消息仅提一个问题。 永远不要在单轮对话中批量提出多个问题。
清单是唯一事实来源。 所有问题都来自清单，新问题在提问前要先添加到清单中。
延后，不要丢弃。 未来任务的问题标记为延后，而非删除。到对应任务阶段时会重新检查其相关性。
做引导者，而非审问者。 提供上下文是为了帮助用户理解问题领域，而非仅仅是为了得到你的问题的答案。
尊重“跳过”操作。 记录默认假设，继续流程，不要给用户压力。
对选项保持中立。 如果你有推荐方案，表述为“我倾向于选择X，因为……”而非“你应该选X”。
保持每个问题区块的可读性——30秒内可以读完。让可视化内容承担信息传递的作用，不要在文字中重复描述。
永远不要询问还未发生的内容。 如果一个问题的相关性取决于未来任务的结果，必须延后处理。

clarifying-assumptions

Original

Translation

Clarifying Assumptions

假设澄清

Purpose

用途

Progressive Disclosure — The Core Principle

渐进式披露——核心原则

Tier 1 — Phase 3 (Upfront Clarification)

第一层——第3阶段（前置澄清）

Tier 2 — Phase 5 (Just-In-Time Clarification)

第二层——第5阶段（即时澄清）

Platform Adaptation

平台适配

Inputs

输入项

Input contract (from upstream skill)

输入契约（来自上游技能）

Output

输出

Output contract (consumed by downstream skills)

输出契约（供下游技能使用）

Subagent Registry

子代理注册表

Core Principles

核心原则

1. Ask only what is relevant NOW

1. 仅询问当前相关的内容

2. Use interactive selection for every discrete choice

2. 所有离散选择都使用交互式选择

3. Give visual context proportional to the question's complexity

3. 提供与问题复杂度匹配的可视化上下文

Execution — Upfront Mode (Phase 3)

执行流程——前置模式（第3阶段）

Phase 1 — Build and present the question manifest

阶段1——构建并展示问题清单

1a. Read and categorize all items

1a. 读取并分类所有项

1b. Prioritize Tier 1 items

1b. 优先级排序第一层项

1c. Present the manifest

1c. 展示清单

Question Manifest for <TICKET_KEY>

<TICKET_KEY> 问题清单

Questions for now (Tier 1)

当前需要处理的问题（第一层）

Deferred questions (will ask before each task)

延后处理的问题（将在对应任务执行前询问）

Phase 2 — Walk through Tier 1 questions one at a time

阶段2——逐个梳理第一层问题

2a. Show progress

2a. 展示进度

2b. Provide context (proportional to complexity — see Principle 3)

2b. 提供上下文（与复杂度匹配——参考原则3）

2c. Ask using the best available input method (see Principle 2)

2c. 使用最佳可用输入方式提问（参考原则2）

2d. Record the answer

2d. 记录答案

Phase 3 — Delegate file updates and summarize

阶段3——委托文件更新并总结

3a. Dispatch decision-recorder

3a. 调度decision-recorder

3b. Handle the result

3b. 处理结果

3c. Final summary

3c. 最终总结

Clarification Complete (Tier 1) — <TICKET_KEY>

澄清完成（第一层）—— <TICKET_KEY>

Execution — Just-In-Time Mode (Phase 5, before each task)

执行流程——即时模式（第5阶段，每个任务执行前）

1. Load deferred questions for this task

1. 加载该任务的延后问题

2. Filter for relevance

2. 过滤相关性

3. Present remaining questions

3. 展示剩余问题

Just-In-Time Clarification — Task <N>: <Title>

即时澄清——任务 <N>: <标题>

4. Delegate file updates

3a. Dispatch
`decision-recorder`

3a. 调度
`decision-recorder`