pre-planning-discussion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pre-Planning Discussion Skill

预规划讨论Skill

Purpose

目的

Resolve specific implementation ambiguities before a plan is created. This is an optional step between design and planning in the feature lifecycle (design → ambiguity resolution → plan → implement → validate → release), or a standalone step before any planning workflow.

The cost of a wrong assumption compounds: a silently wrong assumption at the planning stage produces a valid-looking plan that executes cleanly but delivers the wrong thing. The rework cost is the entire plan-execute cycle, not just a single task. This skill makes assumptions explicit so they can be corrected cheaply — before any code is written.

在制定计划前解决具体的实现歧义。这是功能生命周期中设计与规划之间的可选步骤（设计 → 歧义解决 → 规划 → 实现 → 验证 → 发布），也可作为任何规划工作流前的独立步骤。

错误假设的成本会不断累积：规划阶段的隐性错误假设会生成看似合理的计划，执行过程也顺畅，但最终交付的结果却不符合预期。返工成本是整个计划-执行周期的成本，而非单个任务的成本。本Skill可将假设明确化，以便在编写任何代码前以低成本纠正错误。

Operator Context

操作者上下文

Hardcoded Behaviors (Always Apply)

硬编码行为（始终适用）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before starting
Scope Guardrail: This skill clarifies HOW to implement scoped work. It NEVER expands scope to add new capabilities or question WHETHER the work should be done. If an ambiguity implies scope expansion, classify it as OUT and move on. WHY: scope creep during ambiguity resolution defeats the purpose — the user already decided what to build; we're resolving how.
Prior Decision Carryforward: Check for existing context from earlier phases (feature-design output, prior ambiguity resolution, ADR decisions). Never re-ask a settled question. WHY: re-asking erodes trust and wastes interaction budget.
Structured Output Required: Both modes MUST produce the identical context document format (Resolved Decisions + Carried Forward + Scope Boundary + Canonical References). WHY: downstream consumers (feature-plan, workflow-orchestrator) depend on a predictable format regardless of which mode produced it.
Canonical References Accumulation: Track every spec, ADR, config file, or interface definition referenced during the discussion. These become the "canonical refs" list in the output document. WHY: downstream agents need to know which files are authoritative for the decisions made.

CLAUDE.md 合规性：开始前阅读并遵循仓库中的CLAUDE.md
范围护栏：本Skill仅澄清如何实现限定范围内的工作。绝不扩展范围以添加新功能，也不质疑是否应该开展此项工作。如果某个歧义意味着范围扩展，将其归类为OUT并继续下一步。原因：歧义解决阶段的范围蔓延违背了本Skill的初衷——用户已决定要构建什么，我们只需解决如何构建的问题。
前期决策沿用：检查早期阶段的现有上下文（feature-design输出、前期歧义解决结果、ADR决策）。绝不重复询问已解决的问题。原因：重复询问会损害信任并浪费交互成本。
强制结构化输出：两种模式都必须生成完全相同的上下文文档格式（已解决决策 + 沿用决策 + 范围边界 + 权威参考）。原因：下游使用者（feature-plan、workflow-orchestrator）依赖可预测的格式，无论使用哪种模式生成。
权威参考累积：记录讨论过程中引用的每一份规范、ADR、配置文件或接口定义。这些将成为输出文档中的「权威参考」列表。原因：下游Agent需要了解哪些文件是决策的权威依据。

Default Behaviors (ON unless disabled)

默认行为（除非禁用否则启用）

Mode Auto-Detection: If the working directory has substantial existing code (10+ source files in the relevant domain), default to Assumptions mode. Otherwise, default to Discussion mode. User can override.
Confidence Calibration: In Assumptions mode, be honest about confidence. "Confident" means strong evidence from multiple files. "Likely" means one file or consistent pattern. "Unclear" means conflicting signals or insufficient data. Never inflate confidence.
Interaction Budget: Assumptions mode targets 2-4 user interactions (corrections). Discussion mode targets 3-6 decisions. If either mode drifts beyond these bounds, something is wrong — the scope is too broad, or questions are too granular.

模式自动检测：如果工作目录中有大量现有代码（相关领域有10个以上源文件），默认使用假设模式。否则默认使用讨论模式。用户可手动覆盖。
置信度校准：在假设模式下，如实说明置信度。「确信」意味着多个文件提供了有力证据。「可能」意味着单个文件或一致的模式。「不明确」意味着信号冲突或数据不足。绝不夸大置信度。
交互成本控制：假设模式目标为2-4次用户交互（纠正）。讨论模式目标为3-6个决策。如果任一模式超出此范围，则存在问题——范围过宽或问题过于细化。

Optional Behaviors (OFF unless enabled)

可选行为（除非启用否则禁用）

Auto-approve assumptions: Accept all Confident/Likely assumptions without presenting them (for fast iteration)

自动批准假设：直接接受所有「确信/可能」的假设，无需呈现给用户（用于快速迭代）

What This Skill CAN Do

本Skill可完成的工作

Identify implementation ambiguities (gray areas) and present concrete options
Read codebase files to form evidence-based assumptions
Produce a structured context document consumed by feature-plan or workflow-orchestrator
Carry forward decisions from prior phases
Accumulate canonical references for downstream agents

识别实现歧义（模糊领域）并提供具体选项
读取代码库文件以形成基于证据的假设
生成供feature-plan或workflow-orchestrator使用的结构化上下文文档
沿用前期阶段的决策
为下游Agent累积权威参考

What This Skill CANNOT Do

本Skill不可完成的工作

Expand scope beyond the current task boundary (scope guardrail)
Replace feature-design for broad design exploration
Produce implementation plans (that's feature-plan)
Write code or modify existing files (beyond the context document)

扩展当前任务边界之外的范围（遵守范围护栏）
替代feature-design进行广泛的设计探索
生成实现计划（此项由feature-plan完成）
编写代码或修改现有文件（上下文文档除外）

Instructions

操作说明

Phase 0: PRIME

阶段0：准备（PRIME）

Goal: Load context, detect mode, identify the work to be clarified.

Load prior context: Check for existing artifacts that contain decisions:
- ```
.feature/state/design/
```
  — design documents from feature-design
- ```
adr/
```
  — architecture decision records relevant to this work
- ```
task_plan.md
```
  — any existing plan context
- Prior ambiguity resolution output (if re-running)
Extract carried-forward decisions: From any prior artifacts, extract decisions already made. These go directly into the "Carried Forward" section and are NOT re-asked.
Detect mode: Assess the codebase:
- If the user explicitly requested a mode, use that mode
- If the working directory has substantial existing code in the relevant domain, use Assumptions mode
- Otherwise, use Discussion mode
Identify scope boundary: From the user's request (and any design document), establish:
- IN: What this task covers
- OUT: What this task explicitly does not cover

GATE: Prior context loaded. Mode selected. Scope boundary established. Proceed to Execute.

目标：加载上下文，检测模式，确定需要澄清的工作内容。

加载前期上下文：检查包含决策的现有工件：
- ```
.feature/state/design/
```
  — feature-design生成的设计文档
- ```
adr/
```
  — 与此工作相关的架构决策记录（ADR）
- ```
task_plan.md
```
  — 任何现有计划上下文
- 前期歧义解决输出（如果重新运行）
提取沿用决策：从任何前期工件中提取已做出的决策。这些将直接进入「沿用决策」部分，不会被重复询问。
检测模式：评估代码库：
- 如果用户明确指定了模式，则使用该模式
- 如果工作目录中相关领域有大量现有代码，使用假设模式
- 否则使用讨论模式
确定范围边界：根据用户的请求（以及任何设计文档）确定：
- IN：本任务涵盖的内容
- OUT：本任务明确不涵盖的内容

关卡：已加载前期上下文。已选择模式。已确定范围边界。进入执行阶段。

Phase 1: EXECUTE

阶段1：执行（EXECUTE）

Discussion Mode (greenfield / unclear requirements)

讨论模式（全新项目/需求不明确）

Goal: Surface gray areas — decisions that could go multiple ways — and present them with domain-aware options.

Step 1: Identify Gray Areas

Analyze the task requirements and classify ambiguities by domain:

Domain	Typical Gray Areas
Visual features	Layout density, responsive breakpoints, animation behavior, color scheme interpretation
APIs	Contract shape, error response format, versioning strategy, auth mechanism
CLIs	Flag design, output format (human vs. machine), exit codes, stdin/stdout conventions
Data pipelines	Batch vs. streaming, idempotency guarantees, failure semantics, retry policy
Config/infrastructure	File format, environment variable naming, secret management, deployment strategy
Content/documentation	Audience level, tone, structure, depth, cross-reference strategy

For each gray area, prepare 2-3 concrete options with tradeoffs. NOT open-ended questions.

Step 2: Present Gray Areas

Present all identified gray areas grouped by domain. For each:

markdown

undefined

目标：明确模糊领域——可能有多种处理方式的决策，并结合领域知识提供选项。

步骤1：识别模糊领域

分析任务需求，按领域对歧义进行分类：

领域	典型模糊领域
视觉功能	布局密度、响应式断点、动画行为、配色方案解读
APIs	契约结构、错误响应格式、版本策略、认证机制
CLIs	标志设计、输出格式（人类可读 vs 机器可读）、退出码、stdin/stdout约定
数据管道	批处理 vs 流处理、幂等性保证、失败语义、重试策略
配置/基础设施	文件格式、环境变量命名、密钥管理、部署策略
内容/文档	受众层级、语气、结构、深度、交叉引用策略

针对每个模糊领域，准备2-3个带有权衡的具体选项。避免开放式问题。

步骤2：呈现模糊领域

按领域分组呈现所有识别出的模糊领域。每个模糊领域的呈现格式如下：

markdown

undefined

Gray Area: [descriptive name]

Domain: [Visual / API / CLI / Data / Config / Content]

Options:

[Option A] — [1-sentence tradeoff]
[Option B] — [1-sentence tradeoff]
[Option C] (if applicable) — [1-sentence tradeoff]

Default recommendation: [which option and why, if you have a preference]


Present all gray areas at once (not one at a time) so the user can batch their decisions. If a gray area has an obvious best choice, state the recommendation — the user can accept or override.

**Step 3: Capture Decisions**

For each gray area the user responds to, record:
- The decision made
- The rationale (user's reasoning or acceptance of recommendation)
- Which options were rejected and why

If the user defers a decision ("I don't care" or "whatever you think"), accept your recommendation and record it as "defaulted to recommendation."

Domain: [Visual / API / CLI / Data / Config / Content]

Options:

[Option A] — [1-sentence tradeoff]
[Option B] — [1-sentence tradeoff]
[Option C] (if applicable) — [1-sentence tradeoff]

Default recommendation: [which option and why, if you have a preference]


一次性呈现所有模糊领域（而非逐个呈现），以便用户批量做出决策。如果某个模糊领域有明显的最佳选择，说明推荐理由——用户可接受或覆盖。

**步骤3：记录决策**

针对用户回应的每个模糊领域，记录：
- 做出的决策
- 理由（用户的推理或对推荐的接受）
- 被拒绝的选项及原因

如果用户推迟决策（「无所谓」或「你看着办」），则接受你的推荐，并记录为「默认采用推荐方案」。

Assumptions Mode (brownfield / existing codebase)

假设模式（已有项目/现有代码库）

Goal: Read the codebase, form evidence-based opinions, and present them for the user to correct. The user only intervenes where the agent is actually wrong.

Step 1: Codebase Survey

Read 5-15 files relevant to the task. Selection strategy:

Entry points (main, index, router, handler files)
Configuration (config files, env templates, package manifests)
Files directly related to the area being modified
Test files that reveal conventions
Types/interfaces that define contracts

Step 2: Form Assumptions

For each relevant aspect of the implementation, form an assumption:

markdown

undefined

目标：读取代码库，形成基于证据的判断，并呈现给用户纠正。仅当Agent的判断确实错误时，用户才需要干预。

步骤1：代码库调研

读取与任务相关的5-15个文件。选择策略：

入口文件（main、index、router、handler文件）
配置文件（配置文件、环境变量模板、包清单）
与修改区域直接相关的文件
揭示约定的测试文件
定义契约的类型/接口文件

步骤2：形成假设

针对实现的每个相关方面，形成假设：

markdown

undefined

Assumption: [descriptive name]

Claim: [what you believe is true]
Evidence:
```
path/to/file.ext:L42
```
— [specific pattern observed]
Confidence: Confident | Likely | Unclear
If wrong: [concrete consequence of proceeding with this assumption]


Confidence calibration:
- **Confident**: Multiple files confirm the pattern, or explicit configuration states it
- **Likely**: One file shows the pattern, or it's consistent with the overall codebase style
- **Unclear**: Conflicting signals, insufficient data, or the codebase doesn't address this

**Step 3: Present Assumptions**

Present all assumptions organized by confidence level (Confident first, Unclear last). Tell the user:

> Here's what I believe about this codebase based on reading [N] files. Please correct anything that's wrong. You only need to respond to items that are incorrect — silence means agreement.

**Step 4: Process Corrections**

For each correction the user provides:
- Update the assumption to reflect the correct information
- Note the original (wrong) assumption and why it was wrong
- Adjust confidence on related assumptions if the correction reveals a pattern

Claim: [what you believe is true]
Evidence:
```
path/to/file.ext:L42
```
— [specific pattern observed]
Confidence: Confident | Likely | Unclear
If wrong: [concrete consequence of proceeding with this assumption]


置信度校准：
- **确信**：多个文件确认了该模式，或有明确的配置说明
- **可能**：单个文件显示了该模式，或与代码库整体风格一致
- **不明确**：信号冲突、数据不足，或代码库未涉及此方面

**步骤3：呈现假设**

按置信度顺序呈现所有假设（先确信，最后是不明确）。告知用户：

> 这是我基于读取[N]个文件对代码库的判断。请纠正任何错误内容。你只需回应不正确的条目——无回应即表示同意。

**步骤4：处理纠正**

针对用户提供的每一项纠正：
- 更新假设以反映正确信息
- 记录原（错误）假设及其错误原因
- 如果纠正揭示了新模式，调整相关假设的置信度

Phase 2: COMPILE OUTPUT

阶段2：生成输出（COMPILE OUTPUT）

Goal: Produce the structured context document that downstream skills consume.

Both modes converge here. Produce a single document with this exact structure:

markdown

undefined

目标：生成供下游Skill使用的结构化上下文文档。

两种模式在此处收敛，生成具有以下精确结构的单一文档：

markdown

undefined

Pre-Planning Context: [Task Name]

Resolved Decisions

[For each decision/confirmed assumption]

[ID]: [Choice made] — [Rationale]

[For each decision/confirmed assumption]

[ID]: [Choice made] — [Rationale]

Carried Forward

[Decisions from prior phases that remain valid]

[ID]: [Decision] — (from [source]: design doc / ADR / prior resolution)

[Decisions from prior phases that remain valid]

[ID]: [Decision] — (from [source]: design doc / ADR / prior resolution)

Scope Boundary

IN: [What this task covers]
OUT: [What this task explicitly does not cover]

IN: [What this task covers]
OUT: [What this task explicitly does not cover]

Canonical References

[Files referenced during discussion that downstream agents should consult]

```
path/to/file.ext
```
— [why it's authoritative for this work]

[Files referenced during discussion that downstream agents should consult]

```
path/to/file.ext
```
— [why it's authoritative for this work]

Mode Used

[Discussion | Assumptions] — [brief rationale for mode selection]


Save this document:
- If in a feature lifecycle: save to `.feature/state/design/pre-planning-context-FEATURE.md`
- If standalone: save to `task_plan_context.md` alongside `task_plan.md`

**GATE**: Context document produced with all required sections. All decisions recorded with rationale. Scope boundary defined. Canonical references listed.

[Discussion | Assumptions] — [brief rationale for mode selection]


保存此文档：
- 如果处于功能生命周期中：保存至`.feature/state/design/pre-planning-context-FEATURE.md`
- 如果是独立使用：保存至`task_plan_context.md`，与`task_plan.md`放在同一目录

**关卡**：生成包含所有必填部分的上下文文档。所有决策均记录了理由。已定义范围边界。已列出权威参考。

Phase 3: HANDOFF

阶段3：交接（HANDOFF）

Goal: Confirm completion and suggest next step.

Summarize: "[N] decisions resolved, [M] carried forward, [K] canonical references accumulated."
Suggest next step based on context:
- If in feature lifecycle: "Run
```
/feature-plan
```
  to create the implementation plan."
- If standalone: "Proceed to planning. The context document is at [path]."
If any assumptions were marked "Unclear" and not resolved by the user, flag them:

Warning: [N] assumptions remain unclear. These may need revisiting during planning if they affect task decomposition.

GATE: Handoff complete. Context document saved. Next step communicated.

目标：确认完成并建议下一步。

总结：「已解决[N]个决策，沿用[M]个决策，累积[K]个权威参考。」
根据上下文建议下一步：
- 如果处于功能生命周期中：「运行
```
/feature-plan
```
  以生成实现计划。」
- 如果是独立使用：「进入规划阶段。上下文文档位于[路径]。」
如果有任何标记为「不明确」且未被用户解决的假设，需标记：

警告：尚有[N]个假设不明确。在规划过程中，如果这些假设影响任务分解，可能需要重新审视。

关卡：交接完成。上下文文档已保存。已告知下一步。

Error Handling

错误处理

Error	Cause	Solution
No gray areas found	Task is unambiguous or too vague to analyze	If unambiguous, skip this skill and go to planning. If too vague, return to feature-design
User defers all decisions	User wants the agent to decide everything	Accept all recommendations, record as "defaulted." Proceed.
Scope expansion detected	A gray area implies new capabilities	Classify as OUT in scope boundary. Do not resolve it.
Too many gray areas (>10)	Task scope is too broad	Group related gray areas or suggest breaking the task into smaller pieces
Codebase too small for Assumptions mode	<5 relevant files	Switch to Discussion mode
Conflicting prior decisions	Design doc and ADR disagree	Flag the conflict to the user. Do not resolve silently

错误	原因	解决方案
未找到模糊领域	任务无歧义或过于模糊无法分析	如果无歧义，跳过本Skill直接进入规划。如果过于模糊，返回feature-design
用户推迟所有决策	用户希望Agent全权决定	接受所有推荐方案，记录为「默认采用」。继续下一步。
检测到范围扩展	某个歧义意味着需要添加新功能	在范围边界中标记为OUT。不解决该歧义。
模糊领域过多（>10个）	任务范围过宽	对相关模糊领域进行分组，或建议将任务拆分为更小的部分
代码库过小无法使用假设模式	相关文件不足5个	切换为讨论模式
前期决策冲突	设计文档与ADR不一致	向用户标记冲突。绝不静默解决

Anti-Patterns

反模式

Anti-Pattern	Why Wrong	Do Instead
Asking 15-20 individual questions	Exhausts user patience, most answers are predictable	Use Assumptions mode: form opinions, ask for corrections
Open-ended questions ("How should we handle errors?")	Forces user to design the solution	Present 2-3 concrete options with tradeoffs
Re-asking settled decisions	Wastes interaction budget, erodes trust	Check prior context first; carry forward existing decisions
Expanding scope during discussion	Defeats the purpose of scoped ambiguity resolution	Apply scope guardrail: clarify HOW, never WHETHER
Presenting one option as a question	"Should we use JSON?" is not a gray area if there's only one option	Only present genuine gray areas with multiple valid approaches
Skipping evidence in Assumptions mode	Assumptions without evidence can't be evaluated	Every assumption MUST cite a file path and specific pattern

反模式	错误原因	正确做法
询问15-20个独立问题	耗尽用户耐心，大多数答案可预测	使用假设模式：形成判断，仅请求纠正
开放式问题（「我们应该如何处理错误？」）	迫使用户设计解决方案	提供2-3个带有权衡的具体选项
重复询问已解决的决策	浪费交互成本，损害信任	先检查前期上下文；沿用已有决策
讨论过程中扩展范围	违背了限定范围歧义解决的初衷	遵守范围护栏：仅澄清如何做，绝不质疑是否做
将单个选项作为问题提出（「我们应该使用JSON吗？」）	如果只有一个选项，这并非模糊领域	仅呈现存在多种有效方案的真实模糊领域
假设模式下跳过证据	无证据的假设无法被评估	每个假设都必须引用文件路径和具体模式

Anti-Rationalization

反合理化

See core patterns.

Domain-specific for pre-planning discussion:

Rationalization	Why Wrong	Action
"The requirements are clear, no ambiguities"	Almost every task has ambiguities; you're not looking hard enough	Spend 2 minutes actively looking for gray areas before declaring none exist
"I'll figure it out during implementation"	That's exactly what this skill prevents — silent wrong assumptions	Surface the ambiguity now; it's cheaper to resolve
"This expands scope but it's important"	Scope guardrail is non-negotiable	Mark as OUT, note it for future work
"User will correct me if I'm wrong"	Users don't know what you assumed silently	Make assumptions explicit so they CAN correct you
"Confident enough, no need to show evidence"	Assumptions without evidence are untestable claims	Always cite file path and pattern

参见核心模式。

预规划讨论的领域特定反合理化：

合理化	错误原因	行动
「需求明确，无歧义」	几乎每个任务都存在歧义，只是你没有仔细寻找	在宣布无歧义前，花2分钟主动寻找模糊领域
「我会在实现过程中解决」	这正是本Skill要避免的——隐性错误假设	现在就明确歧义；解决成本更低
「这会扩展范围但很重要」	范围护栏是不可协商的	标记为OUT，记录为未来工作
「如果我错了用户会纠正我」	用户不知道你做出了哪些隐性假设	明确假设以便用户纠正
「足够确信，无需展示证据」	无证据的假设是无法验证的断言	始终引用文件路径和模式

References

参考

Gate Enforcement
Anti-Rationalization
ADR-072: Pre-Planning Ambiguity Resolution

关卡执行
反合理化
ADR-072: Pre-Planning Ambiguity Resolution