beo-exploring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Beo Exploring

Beo 探索流程

Overview

概述

Exploring is the decision-extraction phase. Before any research or planning, you must understand what the user actually wants, including the parts they haven't thought about yet.

Core principle: Every ambiguity resolved here saves 10x rework downstream.

The output is a

CONTEXT.md

file that becomes the single source of truth for all downstream skills (planning, validating, executing, reviewing).

探索流程是决策提取阶段。在任何调研或规划之前，你必须明确用户的真实需求，包括那些他们还没考虑到的部分。

核心原则：在这里解决的每一个歧义，都能避免后续10倍的返工。

输出是一个

CONTEXT.md

文件，它将成为后续所有环节（规划、验证、执行、评审）的唯一事实来源。

Key Terms

核心术语

instant: single-file or similarly tiny work, well-scoped, typically under 30 minutes, with no meaningful planning ambiguity
locked decision: a behavioral choice the user has explicitly confirmed or accepted as a default
gray area: a requirement that would materially change planning or execution if answered differently

instant（即时任务）：单文件或类似的极小工作量任务，范围清晰，通常耗时不超过30分钟，没有明显的规划歧义
locked decision（已锁定决策）：用户已明确确认或接受为默认值的行为选择
gray area（灰色地带）：如果给出不同的答案，会实质性改变规划或执行路径的需求点

Default Exploring Loop

默认探索循环

read any existing context and prior learnings
classify the scope and likely gray areas
ask one focused behavioral question at a time
lock decisions explicitly as they emerge
write
```
CONTEXT.md
```
self-review for completeness, then hand off to planning

Use the reference docs when you need the exact learnings-read protocol or slug-safe update procedure; the default loop above should cover normal use.

阅读所有现有上下文和历史经验
划分范围，识别可能的灰色地带
每次仅提出一个聚焦的行为相关问题
决策明确后即时锁定
编写
```
CONTEXT.md
```
自我评审完整性，然后移交至规划环节

如果需要确切的历史经验读取协议或slug安全更新流程，请参考参考文档；上述默认循环适用于常规场景。

When NOT to Use

不适用场景

Request is instant (single file, well-scoped, <30 min per router classification): router handles this directly, skip to executing
Request is purely a bug fix with clear reproduction steps: use debugging workflow
You're resuming mid-pipeline (router handles this)

需求属于 instant（即时任务）（单文件、范围清晰、按路由分类耗时<30分钟）：由路由直接处理，跳过本流程直接进入执行环节
需求是纯BUG修复，且有清晰的复现步骤：使用调试工作流
你正在流程中途恢复执行：由路由处理

Phase 0: Read Existing Context

阶段0：读取现有上下文

Before asking any questions, check what already exists:

bash

undefined

在提问前，先检查已有内容：

bash

undefined

Check for existing CONTEXT.md

cat .beads/artifacts/<feature-name>/CONTEXT.md 2>/dev/null

Check the epic bead for existing description

br show <EPIC_ID> --json


Use `../reference/references/learnings-read-protocol.md` for the canonical prior-learnings read flow.

If CONTEXT.md already exists with locked decisions, skip to Phase 3 (verify, don't re-ask).

br show <EPIC_ID> --json


参考 `../reference/references/learnings-read-protocol.md` 获取标准的历史经验读取流程。

如果已经存在包含已锁定决策的 CONTEXT.md，直接跳至阶段3（验证，无需重复提问）。

Phase 1: Scope Assessment

阶段1：范围评估

Classify the request before diving into questions.

Signal	Classification	Depth
Trivial rename, config change	Quick	Skip to Phase 3, 1-2 questions max
Clear feature with known boundaries	Standard	Full Phase 2, 3-5 questions
Ambiguous, multi-system, architectural	Deep	Full Phase 2, 5-8 questions + gray areas

在深入提问前先对需求进行分类。

信号	分类	深度
trivial 重命名、配置变更	快速	跳至阶段3，最多1-2个问题
边界清晰的明确功能	标准	完整执行阶段2，3-5个问题
模糊、涉及多系统、架构相关的需求	深度	完整执行阶段2，5-8个问题 + 灰色地带梳理

Phase 2: Decision Extraction

阶段2：决策提取

Step 1: Domain Classification

步骤1：领域分类

Classify the feature into one or more domains:

Domain	Signal	Key Questions
SEE (UI/Visual)	User mentions display, page, component	What does the user see? What triggers it?
CALL (API/Integration)	External services, endpoints, protocols	What's the contract? Auth? Error handling?
RUN (Processing/Logic)	Algorithms, transformations, business rules	What are the inputs/outputs? Edge cases?
READ (Data/Storage)	Database, files, caching	What's the schema? Migration needed?
ORGANIZE (Refactor/Structure)	Code organization, patterns, architecture	What's the target structure? What moves?

将功能归类到一个或多个领域：

领域	信号	核心问题
SEE（UI/视觉）	用户提到展示、页面、组件	用户会看到什么？触发条件是什么？
CALL（API/集成）	外部服务、端点、协议	接口契约是什么？鉴权方式？错误处理逻辑？
RUN（处理/逻辑）	算法、转换、业务规则	输入输出是什么？边界场景有哪些？
READ（数据/存储）	数据库、文件、缓存	schema 是什么？需要迁移吗？
ORGANIZE（重构/结构）	代码组织、模式、架构	目标结构是什么？哪些内容需要迁移？

Step 2: Identify Gray Areas

步骤2：识别灰色地带

For each domain, identify 2-4 areas where the user probably hasn't thought through the details. These are your exploration targets.

Common gray areas:

Error handling behavior (what happens when X fails?)
Edge cases (empty state, max limits, concurrent access)
Migration path (existing data, backward compatibility)
Performance requirements (latency, throughput, caching)
Security implications (auth, validation, sanitization)

对每个领域，找出2-4个用户大概率还没考虑过细节的区域，这些就是你的探索目标。

常见灰色地带：

错误处理行为（X失败时应该如何处理？）
边界场景（空状态、最大值限制、并发访问）
迁移路径（存量数据、向后兼容性）
性能要求（延迟、吞吐量、缓存）
安全影响（鉴权、校验、输入清洗）

Step 3: Socratic Exploration

步骤3：苏格拉底式探索

<HARD-GATE> Ask ONE question at a time. Wait for the user's answer before asking the next question. Do NOT batch multiple questions in a single message. </HARD-GATE>

<硬性要求> 每次仅提一个问题，等用户回答后再提下一个问题。禁止在单条消息中批量提出多个问题。 </硬性要求>

Example: Good vs Bad Exploring Question

示例：好的探索问题 vs 坏的探索问题

Bad: "Should we use a queue or a cron job?" Why bad: this asks the user to choose implementation rather than behavior.

Good: "If this job fails overnight, what should the user see the next morning?" Why good: this locks behavior that planning can later implement in different ways.

For each gray area:

State what you currently understand
State the specific ambiguity
Ask a focused, answerable question
If the user says "I don't know" or "whatever you think", propose a concrete default and ask for confirmation

坏问题："Should we use a queue or a cron job?" 错误原因：这个问题要求用户选择实现方案而非明确行为。

好问题："If this job fails overnight, what should the user see the next morning?" 优势：这个问题锁定了行为，后续规划阶段可以选择不同的实现方式。

针对每个灰色地带：

说明你当前的理解
说明具体的歧义点
提出一个聚焦、可回答的问题
如果用户说"I don't know"或"whatever you think"，提出一个具体的默认方案并请求确认

Default-Proposal Pattern

默认方案提议模式

When the user does not want to decide directly:

state the uncertainty plainly
propose one concrete default
explain the consequence of that default in behavioral terms
ask for confirmation or correction

Example: "You do not seem to care about retry behavior here. I suggest one automatic retry and then a visible failure state so the user is not left guessing. Should I lock that?"

Question quality checklist (apply to every question before asking):

Is this answerable in 1-2 sentences?
Does this affect implementation decisions?
Am I asking about BEHAVIOR, not IMPLEMENTATION? (users decide what, not how)
Have I already asked this or can I infer it?

当用户不想直接做决策时：

直白说明不确定性
提出一个具体的默认方案
用行为层面的表述解释该默认方案的影响
请求确认或修正

示例："You do not seem to care about retry behavior here. I suggest one automatic retry and then a visible failure state so the user is not left guessing. Should I lock that?"

问题质量检查清单（每个问题提出前都要检查）：

这个问题可以用1-2句话回答吗？
这个问题会影响实现决策吗？
我问的是行为，不是实现吗？（用户决定做什么，而非怎么做）
我是不是已经问过这个问题，或者可以从现有信息推断出来？

Step 4: Lock Decisions

步骤4：锁定决策

As the user answers, assign stable IDs to each decision:

D1: Authentication uses JWT tokens with 1-hour expiry
D2: Error responses follow RFC 7807 Problem Details format
D3: Database migration runs as a separate step, not on startup
D4: Rate limiting is 100 req/min per API key

Confirm each decision explicitly: "Locking D3: Database migration runs as a separate step. Correct?"

用户给出回答后，为每个决策分配固定ID：

D1: Authentication uses JWT tokens with 1-hour expiry
D2: Error responses follow RFC 7807 Problem Details format
D3: Database migration runs as a separate step, not on startup
D4: Rate limiting is 100 req/min per API key

每个决策都要明确确认："Locking D3: Database migration runs as a separate step. Correct?"

Completion Criteria

完成条件

Stop asking questions when ALL of these are true:

Every identified gray area has a locked decision or explicit "out of scope"
You could explain the feature to another developer and they could start planning
No remaining questions would change the high-level approach

<HARD-GATE> If you cannot check all three boxes, keep asking. Do not proceed to Phase 3. </HARD-GATE>

当以下所有条件都满足时，停止提问：

所有识别出的灰色地带都已有锁定决策，或被明确标记为"超出范围"
你可以向另一个开发者解释这个功能，对方可以直接开始规划
没有剩余会影响整体方案的问题

<硬性要求> 如果你不能满足以上三个条件，继续提问，不要进入阶段3。 </硬性要求>

Phase 3: Context Assembly

阶段3：上下文组装

Write the CONTEXT.md file with all locked decisions.

将所有已锁定的决策写入 CONTEXT.md 文件。

CONTEXT.md Structure

CONTEXT.md 结构

markdown

undefined

markdown

undefined

Feature: <feature-name>

Request

Scope Classification

Complexity: <quick/standard/deep>
Domains: <SEE, CALL, RUN, READ, ORGANIZE>
Estimated blast radius: <number of files/modules affected>

Complexity: <quick/standard/deep>
Domains: <SEE, CALL, RUN, READ, ORGANIZE>
Estimated blast radius: <number of files/modules affected>

Locked Decisions

D1: <decision title>

<Full decision description> - Rationale: <why this choice> - Alternatives considered: <what was rejected and why>

D2: <decision title>

...

Out of Scope

<Thing explicitly excluded and why>

<Thing explicitly excluded and why>

Open Questions (for planning)

<Questions that need research, not user input>

<Questions that need research, not user input>

Relevant Patterns

<Patterns from critical-patterns.md that apply>

undefined

<Patterns from critical-patterns.md that apply>

undefined

Write the File

编写文件

bash

undefined

bash

undefined

Create the artifacts directory

mkdir -p .beads/artifacts/<feature-name>

Write CONTEXT.md (use your file editing tools)

undefined

undefined

Slug Preservation

Slug 保留规则

Load

../reference/references/slug-protocol.md

and follow the safe-update procedure exactly whenever updating the epic description.

Also update the epic bead description with a summary using the canonical slug-first shape.

每次更新史诗描述时，读取

../reference/references/slug-protocol.md

并严格遵循安全更新流程。

同时使用标准的slug优先格式更新史诗bead的描述摘要。

Phase 4: Self-Review

阶段4：自我评审

Before handing off, verify the CONTEXT.md quality:

Completeness check: for each locked decision, ask:

Would a developer reading only this file understand the decision?
Is the rationale clear enough to prevent someone from re-opening the discussion?
Are there implicit assumptions that should be explicit?

90% confidence test: "Could a competent developer plan this feature using only CONTEXT.md?"

If yes → proceed to handoff
If no → identify what's missing and go back to Phase 2

移交前，验证 CONTEXT.md 的质量：

完整性检查：针对每个已锁定决策，确认：

仅阅读该文件的开发者能理解这个决策吗？
决策理由是否清晰，足以避免后续有人重新讨论该问题？
是否有应该明确写出的隐含假设？

90%置信度测试："能力合格的开发者仅依靠 CONTEXT.md 就能规划这个功能吗？"

是 → 进入移交环节
否 → 找出缺失的信息，回到阶段2

Phase 5: Handoff

阶段5：移交

Update State

更新状态

Write

.beads/STATE.md

markdown

undefined

编写

.beads/STATE.md

：

markdown

undefined

Beo State

Phase: exploring → complete
Feature: <epic-id> (<feature-name>)
Tasks: 0 (exploring does not create tasks)
Next: beo-planning

Decisions: <count> locked

undefined

Phase: exploring → complete
Feature: <epic-id> (<feature-name>)
Tasks: 0 (exploring does not create tasks)
Next: beo-planning

Decisions: <count> locked

undefined

Announce

通知用户

Report to user:

Exploring complete.
- <N> decisions locked (D1-D<N>)
- <M> items marked out of scope
- <K> open questions for planning phase

Ready to plan. Load beo-planning to begin research and decomposition.

向用户报告：

Exploring complete.
- <N> decisions locked (D1-D<N>)
- <M> items marked out of scope
- <K> open questions for planning phase

Ready to plan. Load beo-planning to begin research and decomposition.

Context Budget

上下文用量预算

If context usage exceeds 65%, use

../reference/references/state-and-handoff-protocol.md

for the canonical base

HANDOFF.json

and

STATE.md

shapes, then add exploring-specific fields such as

decisions_locked

and

open_questions

before pausing.

如果上下文用量超过65%，参考

../reference/references/state-and-handoff-protocol.md

获取标准的

HANDOFF.json

和

STATE.md

基础结构，然后添加探索阶段特有的字段如

decisions_locked

和

open_questions

，之后暂停流程。

Red Flags

风险预警

Flag	Description
Asking implementation questions	"Should we use a Map or an Object?" is planning, not exploring
Batching 3+ questions	One question at a time. Period.
Accepting "I don't care"	Propose a concrete default instead
Skipping gray areas	Every feature has at least 2 gray areas
Writing CONTEXT.md before decisions are locked	Decisions first, document second
Spending >15 min on one question	If it's that complex, lock what you can and mark the rest as an open question for planning

预警项	描述
询问实现相关问题	"Should we use a Map or an Object?" 属于规划环节内容，不属于探索环节
批量提出3个以上问题	每次只能提一个问题，没有例外
接受"我无所谓"的回复	应该提出具体的默认方案
跳过灰色地带	每个功能至少有2个灰色地带
在决策锁定前编写CONTEXT.md	先锁定决策，再编写文档
单个问题耗时超过15分钟	如果问题太复杂，锁定能确定的部分，剩余部分标记为规划阶段的待解决问题

Anti-Patterns

反模式

Pattern	Why It's Wrong	Instead
Starting to plan during exploring	Premature commitment	Lock decisions only; planning comes next
Asking about tech stack choices	That's a planning decision	Ask about behavior and requirements
Copying the user's words verbatim as decisions	Users speak loosely	Restate precisely and confirm
Creating tasks during exploring	No tasks until planning	Only the epic bead should exist
Skipping exploring for non-instant features	Even "simple" features (lightweight and above) still have gray areas	At minimum, do a Quick-depth pass. Only instant requests (single file, <30 min) skip exploring.

反模式	错误原因	正确做法
在探索阶段就开始规划	属于过早承诺	仅锁定决策，规划环节后续再做
询问技术栈选择	属于规划环节的决策	询问行为和需求
直接复制用户的原话作为决策	用户的表述通常比较随意	要精准重述后再确认
在探索阶段创建任务	规划阶段前不要创建任务	仅保留史诗bead即可
非即时需求跳过探索环节	即使是"简单"功能（轻量及以上）也有灰色地带	至少要做一次快速深度的梳理。只有 instant（即时任务）（单文件、<30分钟）可以跳过探索环节。